http/host.ts

Host verification — refusing requests addressed to a name the server doesn't answer to, which is how DNS rebinding reaches a loopback server.

In a rebinding attack, a page on an attacker's domain re-resolves that domain to 127.0.0.1 and talks to the local server same-origin: its GETs carry no Origin header, so the origin allowlist (http/origin.ts) doesn't apply. The Host header gives it away — the browser sets it from the URL, so it names the attacker's domain, never localhost.

A host is allowed when its name is loopback (localhost, 127.0.0.0/8, [::1]), at any port — a rebinding page can't put one of those in Host — or when an allowed origin names it (the allowlist is where the server's UI is served from, so its hosts are the server's own names). Matching reuses the origin matchers, so http://localhost:* or https://*.fuz.dev admit the hosts they'd admit as origins.

A request without a Host header passes: browsers always send one, so its absence means a non-browser client, which the auth stack governs. An empty Host and more than one Host are refused (RFC 9112 §3.2), read from the lines the client sent (get_header_lines) — on @hono/node-server a WebSocket upgrade's own Headers keep only the first Host line, and on a runtime that joins repeated lines (a, b) the comma names no host.

The gate is on by default (AppServerOptions.host_gate). A refusal is said in the log as well as answered: the first in each HOST_REFUSAL_WARN_INTERVAL_MS is a warning naming the refused Host (quoted ASCII-only and truncated, since the client wrote it) and the env var that lists the server's names, with a count of the refusals the interval held back. The response says neither, so a client learns nothing about the allowlist.

Twin of the Rust spine's fuz_http::host.

view source

Declarations
#

12 declarations

allows_host
#

http/host.ts view source

(host: string, allowed_patterns: readonly RegExp[]): boolean import {allows_host} from '@fuzdev/fuz_app/http/host.js';

Check one Host value: loopback, or named by an allowed origin on either scheme. Twin of the Rust AllowedOrigins::allows_host.

host

one Host header value

type string

allowed_patterns

the matchers parse_allowed_origins built

type readonly RegExp[]

returns

boolean

whether the server answers to it

allows_request_hosts
#

http/host.ts view source

(hosts: readonly string[], allowed_patterns: readonly RegExp[]): boolean import {allows_request_hosts} from '@fuzdev/fuz_app/http/host.js';

Host check for a request's Host lines — true when there are none, or one (read_host of http/request_headers.ts: printable ASCII, no space or comma) that passes allows_host. An empty line, more than one line (RFC 9112 §3.2), and a byte outside that set are refused. Twin of the Rust AllowedOrigins::allows_request_hosts.

hosts

the request's Host lines, [] for none

type readonly string[]

allowed_patterns

the matchers parse_allowed_origins built

type readonly RegExp[]

returns

boolean

whether the request passes the host gate

create_host_gate_middleware
#

http/host.ts view source

(options: HostGateOptions): MiddlewareHandler import {create_host_gate_middleware} from '@fuzdev/fuz_app/http/host.js';

Middleware enforcing allows_request_hosts, refusing with 403 {"error": "forbidden_host"} and warning (rate-limited, module doc).

options

the allowlist, the log, and the warning's clock

returns

MiddlewareHandler

the Hono middleware

create_host_gate_middleware_spec
#

http/host.ts view source

(options: HostGateOptions): MiddlewareSpec import {create_host_gate_middleware_spec} from '@fuzdev/fuz_app/http/host.js';

The host gate as a middleware spec on every path (HOST_MIDDLEWARE_PATH), declaring its 403, so the surface and each route's error map carry it.

options

the allowlist, the log, and the warning's clock

returns

MiddlewareSpec

the spec

create_host_refusal_warnings
#

http/host.ts view source

(): HostRefusalWarnings import {create_host_refusal_warnings} from '@fuzdev/fuz_app/http/host.js';

Create the refusal warning's rate limit.

returns

HostRefusalWarnings

format_host_refusal_warning
#

http/host.ts view source

(host: string, allowed_origins_var: string, held_back: number): string import {format_host_refusal_warning} from '@fuzdev/fuz_app/http/host.js';

The refusal warning's text. Twin of the Rust format_host_refusal_warning.

host

the refused Host as the request carried it — several lines joined with ,

type string

allowed_origins_var

the env var the allowlist was read from

type string

held_back

the refusals held back since the last warning

type number

returns

string

one log line

host_gate_middleware_shape
#

http/host.ts view source

{ readonly name: "host"; readonly path: "*"; readonly errors: readonly [RestErrorDef<403, "forbidden_host", Record<never, never>>]; } import {host_gate_middleware_shape} from '@fuzdev/fuz_app/http/host.js';

The host gate's spec without its handler — what the surface and each route's error map read, so a stub surface (create_test_app_surface_spec) lists the same layer.

HOST_MIDDLEWARE_PATH
#

http/host.ts view source

"*" import {HOST_MIDDLEWARE_PATH} from '@fuzdev/fuz_app/http/host.js';

Where the host gate mounts — every path, as the Rust stack mounts it in every group.

HOST_REFUSAL_WARN_INTERVAL_MS
#

http/host.ts view source

60000 import {HOST_REFUSAL_WARN_INTERVAL_MS} from '@fuzdev/fuz_app/http/host.js';

The shortest gap between two refusal warnings, in milliseconds; the refusals between are counted and reported with the next one.

HostGateOptions
#

http/host.ts view source

HostGateOptions import type {HostGateOptions} from '@fuzdev/fuz_app/http/host.js';

allowed_origins

The matchers parse_allowed_origins built — the server's allowlist.

type readonly RegExp[]

log

Where the refusal warning goes.

type Logger

allowed_origins_var?

The env var the allowlist was read from, named in the warning. Defaults to ALLOWED_ORIGINS_VAR.

type string

now?

The clock the warning's rate limit reads, in milliseconds. Defaults to Date.now.

type (): number

returns number

HostRefusalWarnings
#

http/host.ts view source

HostRefusalWarnings import type {HostRefusalWarnings} from '@fuzdev/fuz_app/http/host.js';

Counts refusals between warnings, so a flood of foreign Hosts writes one line per HOST_REFUSAL_WARN_INTERVAL_MS and holds no per-host state.

note

Record a refusal at now_ms: the refusals held back since the last warning when this one is warned, null when it is held back itself.

type (now_ms: number): number | null

now_ms

type number
returns number | null

is_loopback_host
#

http/host.ts view source

(host: string): boolean import {is_loopback_host} from '@fuzdev/fuz_app/http/host.js';

True when host (a Host header value, name[:port]) names a loopback address: localhost, an IPv4 address in 127.0.0.0/8, or [::1].

Anything after the name but a : and a port (decimal digits, at most 65535) makes it not loopback: [::1]junk, localhost:abc, and localhost: 1 are refused. Twin of the Rust is_loopback_host.

host

one Host header value

type string

returns

boolean

whether it names a loopback address

Depends on
#

Imported by
#