Validate webhook target hostname Unicode/homograph normalization in src/webhooks/ssrfGuard.ts

[Jagadeeshftw]

📌 Description

src/webhooks/ssrfGuard.ts validates webhook targets, but its hostname handling does not normalize internationalized/Unicode hostnames (IDNA/punycode) before the safety checks. A homograph or non-normalized Unicode hostname could be presented that bypasses string-based checks while resolving to an unexpected host.

💡 Why it matters: SSRF guards that compare raw (non-normalized) hostnames can be evaded with Unicode look-alikes; normalization to punycode before validation closes that gap.

🧩 Requirements and context

• Normalize the hostname to ASCII/punycode (IDNA) before applying allow/deny and private-range checks.
• Reject hostnames that fail normalization or contain disallowed characters.
• Ensure the normalized hostname is what gets resolved/connected to (consistency between check and use).
• Add tests with Unicode/IDN and homograph hostnames alongside normal ASCII hosts.

Non-functional requirements

• Must be secure, tested, and documented.
• Should be efficient and easy to review.

🛠️ Suggested execution

1. Fork the repo and create a branch

git checkout -b fix/ssrf-idna-normalization

2. Implement changes

• Write/modify the relevant source: src/webhooks/ssrfGuard.ts
• Write comprehensive tests: a new spec under tests/webhooks/
• Add documentation: inline TSDoc on normalization rules
• Include TSDoc doc comments
• Validate security assumptions: check-vs-use consistency

3. Test and commit

• Run tests:

npm test

• Cover edge cases: IDN host, homograph host, invalid Unicode, normal host
• Include test output and security notes in the PR description.

Example commit message

fix(ssrf): normalize hostnames to punycode before validation

✅ Acceptance criteria

• Hostnames normalized to ASCII/punycode before checks
• Non-normalizable/disallowed hostnames rejected
• The validated hostname is the one used to connect
• Tests cover IDN/homograph cases

🔒 Security notes

Confirm there is no check-then-use mismatch that lets a different host be contacted than validated.

📋 Guidelines

• Minimum 95% test coverage
• Clear documentation
• Timeframe: 96 hours

[Ssoleed]

@Ssoleed has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

hi maintainer, can i work on this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ssoleed to this issue.

[drips-wave]

Congratulations, @Ssoleed! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Ssoleed: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊