GitHub

API reference for origin.

Which browser origins a server lets open a WebSocket or call an RPC endpoint (cross-site WebSocket hijacking and RPC CSRF). A browser sends Origin on every WebSocket handshake and cross-origin POST with the user's cookies, so a request whose Origin is neither the server's own (its Host) nor listed in AllowedOrigins is refused with 403. A request without Origin did not come from a browser page and passes.

Same-origin only is the default; list more with AllowedOrigins::

layer.succeed(AllowedOrigins, origin.allow("https://app.example"))

Re-exports

Values

AttributeTypeDescription
Origintype[Origin]

A serialized origin, scheme://host[:port], lowercased and without the scheme's default port; or null (an opaque origin).

SAME_ORIGINOriginPolicy

Only the server's own origin (the default).

ANY_ORIGINOriginPolicy

Every origin: for a public API that authenticates without cookies.

Classes

Functions

parse_origin

parse_origin(text) -> Origin | None

text as an origin; None when it is not scheme://authority alone (a path, query, fragment or userinfo).

ParameterTypeDescription
textstr

Returns Origin | None

def parse_origin(text: str) -> Origin | None:
    """``text`` as an origin; ``None`` when it is not ``scheme://authority``
    alone (a path, query, fragment or userinfo)."""
    if text == "null":
        return Origin(text)
    parts = split_url(text)
    if parts is None:
        return None
    scheme = parts.scheme.lower()
    if not scheme or parts.path or parts.query or parts.fragment or text.endswith("#"):
        return None
    if parse_authority(parts.netloc) is None:
        return None
    return Origin(f"{scheme}://{_host_port(scheme, parts.netloc)}")

allow

allow(*origins) -> OriginPolicy

The server's own origin and origins (https://app.example); a ValueError names one that is not an origin.

ParameterTypeDescription
originsstr = ()

Returns OriginPolicy

def allow(*origins: str) -> OriginPolicy:
    """The server's own origin and ``origins`` (``https://app.example``);
    a ``ValueError`` names one that is not an origin."""
    parsed: set[Origin] = set()
    for text in origins:
        origin = parse_origin(text)
        if origin is None:
            raise ValueError(f"not an origin (scheme://host[:port]): {text!r}")
        parsed.add(origin)
    return OriginPolicy(frozenset(parsed))

origin_allowed

origin_allowed(request) -> Effect[bool]

Whether AllowedOrigins lets request go on.

ParameterTypeDescription
requestServerRequest

Returns Effect[bool]

def origin_allowed(request: ServerRequest) -> Effect[bool]:
    """Whether ``AllowedOrigins`` lets ``request`` go on."""
    sent = request.headers.get("origin")
    authority, scheme = _own(request)
    return AllowedOrigins().flat_map(lambda policy: succeed(policy.allows(sent, authority, scheme)))

require_allowed_origin

require_allowed_origin(request) -> Effect[None, HttpServerError]

Fail with OriginNotAllowed (403) unless AllowedOrigins lets request go on: what every WebSocket upgrade and RPC call runs.

ParameterTypeDescription
requestServerRequest

Returns Effect[None, HttpServerError]

def require_allowed_origin(request: ServerRequest) -> Effect[None, HttpServerError]:
    """Fail with ``OriginNotAllowed`` (403) unless ``AllowedOrigins`` lets
    ``request`` go on: what every WebSocket upgrade and RPC call runs."""

    def check(allowed: bool) -> Effect[None, HttpServerError]:
        if allowed:
            return void
        sent = request.headers.get("origin")
        return fail(HttpServerError(OriginNotAllowed(request, f"Origin {sent!r} is not allowed")))

    return origin_allowed(request).flat_map(check)