Module auth 

Authentication and request-guard primitives for the browser bridge.

The trust boundary, stated once: a request is trusted only if it presents the session token AND is not a cross-origin browser request; everything else is denied. A localhost bind is necessary but not sufficient — it stops off-host access but not other local users/processes, nor web pages the operator visits. See ADR-0036.

The functions here are deliberately small and operate on borrowed primitives rather than framework types so the security checks can be unit-tested in isolation from axum / tungstenite.

Enums

ScopeError

Reason an outbound URL was rejected by validate_outbound_url.

Constants

BRIDGE_HEADER

Custom header every control-plane request must carry. A custom header forces a CORS preflight that the server refuses, blocking simple-request CSRF.

BRIDGE_HEADER_VALUE

Required value of BRIDGE_HEADER.

BRIDGE_TARGET_HEADER

Optional header selecting which connected tab a control-plane request targets.

TOKEN_ENV

Environment variable an operator may use to pin the session token instead of letting the bridge generate one. Never read from argv (ps//proc expose it).

Functions

bearer_matches

Checks an Authorization header value against the expected token.

constant_time_eq

Constant-time string comparison, to avoid leaking the token via timing.

generate_token

Generates a fresh random session token (256 bits, URL-safe base64).

has_bridge_header

Whether the request carries the mandatory X-Omni-Bridge: 1 header.

header_is_safe

Rejects header names/values that could smuggle a second header or request line via CR/LF (or other control characters).

host_allowed

Whether host is an allowed loopback authority for control_port.

is_browser_originated

Whether a request looks browser-originated and must therefore be denied.

normalize_request_path

Normalises a decoded request path, rejecting traversal and control characters. Run before the /__bridge/ routing/auth split so a percent-encoded segment cannot bypass the prefix check.

resolve_existing_token

Resolves an existing session token for a client.

resolve_token

Resolves the session token, in priority order:

validate_outbound_url

Enforces the default-closed outbound scope.

ws_origin_allowed

Whether a WebSocket upgrade’s Origin is permitted.

ws_subprotocol_token

Extracts and verifies the bridge token from WebSocket subprotocols.