Pyjoyment.Plugin.AllowedHosts - Host and Origin validation plugin

# Pyjoyment
app.plugin('AllowedHosts')

# Pyjoyment.Lite
plugin('AllowedHosts')

# The hosts of a deployment, and the origins of its pages
app.plugin('AllowedHosts', hosts=['example.com', '.example.com'], origins=['https://app.example.com'])

# Only for some routes, under the helper "allowed_hosts"
app.plugin('AllowedHosts', hook=False)
mcp = app.routes.under('/mcp', lambda c: c.allowed_hosts())
mcp.post('/').to(cb=lambda c: c.render(json={'jsonrpc': '2.0'}))

Pyjoyment.Plugin.AllowedHosts rejects a request whose Host header is not one of the hosts of the application, with 421 Misdirected Request, and a request whose Origin header, which a browser sends with a request of a page of another site, is not one of its origins, with 403 Forbidden. A request without Origin, which a browser sends without it only for a page of the same site, and a client that is not a browser, passes.

It protects a server on localhost against DNS rebinding: a page of another site whose host name the attacker makes an address of 127.0.0.1 requests the server with its own host in Host, which is not one of the hosts, and with its own origin, which is not one of the origins, as for a server of the Model Context Protocol, whose transport over HTTP requires it.

The host is the one of Host, the host of Pyjo.URL.Pyjo_URL.to_abs() of the request, which a reverse proxy passes on.

See Pyjoyment.Plugins for a list of plugins that are available by default.

Options

Pyjoyment.Plugin.AllowedHosts supports the following options.

hook

app.plugin('AllowedHosts', hook=False)

Check every request of the application, in a hook of ``before_dispatch``,
defaults to ``True``. With ``False``, only the routes under the helper
``allowed_hosts`` are checked.

hosts

app.plugin('AllowedHosts', hosts=['example.com', 'localhost:3000', '.example.org'])
app.plugin('AllowedHosts', hosts=[re.compile(r'^pr-\d+\.example\.com$')])
app.plugin('AllowedHosts', hosts=lambda c, host: host.endswith('.internal'))

The hosts of the application, defaults to ``localhost``, ``127.0.0.1``
and ``[::1]``. A host without a port is of any port, one with a port of
that port only, one that starts with a dot of the domain and its
subdomains, a regular expression searches the host and its port, as
``Host`` has them, and a function takes the controller and the host and
its port, and returns true for one of the application. The names of the
hosts are compared without their case.

origins

app.plugin('AllowedHosts', origins=['https://app.example.com', 'http://localhost:5173'])
app.plugin('AllowedHosts', origins=lambda c, origin: origin.startswith('https://'))

The origins of the pages that request the application, defaults to the
origins of the hosts of ``hosts``, of any scheme. An origin is a scheme, a
host and a port, as a host of ``hosts`` with its scheme, and a function
takes the controller and the origin, as ``Origin`` has it.

Helpers

Pyjoyment.Plugin.AllowedHosts implements the following helpers.

allowed_hosts

boolean = c.allowed_hosts()
boolean = c.allowed_hosts(hosts=['mcp.example.com'])

mcp = app.routes.under('/mcp', lambda c: c.allowed_hosts(hosts=['mcp.example.com']))
mcp.post('/').to(cb=lambda c: c.render(json={'jsonrpc': '2.0'}))

Check the request, with the options of the plugin, or with ``hosts`` and
``origins`` of its own, and render the response of a request that is not
allowed, so that it is false and ends the dispatch of :meth:`under
<Pyjoyment.Routes.Route.Pyjoyment_Routes_Route.under>`, which a condition
of a route would not do, as the next route would match the request.

See also

Pyjoyment, https://mojolicious.org.

It has no counterpart in Mojolicious.

Classes

class Pyjoyment.Plugin.AllowedHosts.Pyjoyment_Plugin_AllowedHosts[source]

Pyjoyment.Plugin.AllowedHosts inherits all methods from Pyjoyment.Plugin and implements the following new ones.

register(app: Pyjoyment_App, conf: dict[str, Any] | None = None) → None[source]
plugin.register(Pyjoyment.new())
plugin.register(Pyjoyment.new(), {'hosts': ['example.com']})

Register the hook and the helper in Pyjoyment application.