Summary
Koa's ctx.hostname API naively parses the HTTP Host header and fails to validate that it complies with RFC 3986 hostname syntax, particularly when @ is present.
If an attacker can send crafted HTTP requests to an affected Koa application that relies on ctx.hostname for security-sensitive logic or URL generation, they may be able to perform Host header injection attacks and influence generated links or routing behavior.
Affected context
This vulnerability occurs in Koa applications that:
- Run on versions prior to 3.1.2 or 2.16.4
- Use
ctx.hostnameas the source of truth for application hostname - Trust the Host header implicitly for generating external URLs (e.g., password resets, email verification, login links, canonical URLs) or for routing and access control decisions
The issue is more impactful in deployments where the application is directly exposed to the internet or where upstream components (load balancers, proxies, API gateways) do not enforce strict Host header validation.
Exploit preconditions
- Attack surface: HTTP/HTTPS interface of a Koa application.
- Required access: Ability to send HTTP requests to the application (typically unauthenticated).
- Trigger point: Any code path that reads
ctx.hostnameand uses it for: - Constructing absolute URLs (password reset, verification, magic login links, redirect targets).
- Generating links in emails or templates.
- Implementing routing, tenant selection, or security checks based on hostname.
- Why exploitation is possible: Koa parses the Host header by taking everything before the first colon and exposes it as
ctx.hostnamewithout validating that it is a syntactically valid host. When the Host header contains an@symbol, the value before@can be attacker-controlled in a way that applications may treat as a trusted hostname, enabling Host header injection.
Why this happens
The root cause is improper input validation of the HTTP Host header in the ctx.hostname API.
Instead of enforcing RFC 3986 hostname rules or rejecting malformed values, Koa performs a naive split on the first colon and assumes the preceding substring is a valid hostname. When a Host header includes an @ character, the parsing logic can yield an attacker-controlled ctx.hostname that does not correspond to a legitimate host for the application.
This behavior maps to CWE-20: Improper Input Validation, where externally supplied data (the Host header) is accepted and propagated without adequate syntactic or semantic checks, allowing it to be misused in downstream security-sensitive logic such as URL generation and routing.
Potential impact
- Attackers could cause password reset, email verification, or magic login links to point to attacker-controlled domains.
- Users may be tricked into submitting credentials or sensitive data to spoofed sites via poisoned links generated by the application.
- Host-based routing or multi-tenant logic could be influenced to serve incorrect tenant data or bypass access controls.
- Security mechanisms that rely on comparing
ctx.hostnameto an allowlist may be bypassed due to malformed but accepted hostnames. - Application logs, metrics, or monitoring systems could be polluted with attacker-controlled hostnames, complicating incident response.
General mitigation guidance
Effective mitigation focuses on strict validation of hostnames and decoupling security decisions from untrusted headers:
- Treat the HTTP Host header as untrusted input; do not rely on it directly for security-sensitive operations.
- Implement hostname validation that enforces RFC-compliant syntax, rejecting or normalizing values containing illegal characters such as
@. - Prefer using a configured canonical application base URL from trusted configuration (environment variables, deployment settings) when generating absolute links for emails or redirects, instead of deriving it from
ctx.hostname. - When host-based routing or multi-tenancy is required, validate the derived hostname against a strict allowlist of known domains and subdomains.
- Place Koa behind a reverse proxy or load balancer that enforces valid Host headers and drops or rewrites malformed requests.
- Reduce the blast radius by ensuring that incorrect hostnames cannot grant elevated privileges, access to additional tenants, or unexpected functionality.
How teams detect issues like this
Detection typically combines code-level review with runtime monitoring:
- Static analysis and code review:
- Search for usages of
ctx.hostname, particularly in: - URL generation helpers.
- Email link generation (password reset, verification, login).
- Redirect logic and router configuration.
- Multi-tenant or domain-based access control code.
- Flag patterns where
ctx.hostnameis used without validation or allowlisting. - Introduce linting or custom static analysis rules that require hostname validation before use in security-sensitive contexts.
- Configuration and policy checks:
- Ensure infrastructure policies enforce valid Host headers at load balancers, API gateways, and reverse proxies.
- Add deployment checks to verify that a canonical base URL is configured and used for critical flows.
- Runtime monitoring:
- Log and analyze Host header values, alerting on malformed hosts or unexpected characters such as
@, spaces, or control characters. - Monitor for anomalous domains appearing in generated links, email templates, or redirect targets.
Automated SAST tools and CI-integrated code scanners can help highlight unvalidated use of ctx.hostname and similar APIs across large Koa codebases.

