linux_patch_manager/tasks/ws-origin-check-spec.md

WS Origin Allowlist — Specification

Issue: #10 Component: crates/pm-web/src/routes/ws.rs Spec version: 0.1.0 (draft) Status: Awaiting Kelly sign-off

---

1. Goal

Harden the browser-facing WebSocket upgrade endpoint (GET /api/v1/ws/jobs) against Cross-Site WebSocket Hijacking (CSWSH) by validating the Origin header against a configured allowlist. The existing single-use, 60-second ticket mechanism is retained as the first credential factor; the Origin check is the second factor.

2. Non-Goals

• Replacing or weakening the ticket mechanism.
• Binding the ticket to a specific WebSocket connection at issuance time (separate, larger change).
• Origin/CORS checks on the JWT-authenticated ticket-issuance endpoint (POST /api/v1/ws/ticket) — it is already protected by JWT + RBAC middleware and is not a browser-only entry point.
• Changes to pm-worker/ws_relay.rs — that module is an outbound mTLS WS client to agents, not a server, and is not reachable from a browser.

3. Design

3.1 Handler change (crates/pm-web/src/routes/ws.rs)

The ws_handler function (lines 96–137) gains a new HeaderMap extractor and performs an Origin allowlist check before ticket validation.

Order of operations in the new handler:

1. Extract HeaderMap (new).
2. Read Origin header. If absent → reject 403 forbidden_origin ("Origin header required").
3. Normalize and compare against the configured allowlist. If not matched → reject 403 forbidden_origin ("Origin not allowed").
4. Existing ticket validation (lines 101–127) runs unchanged.
5. Existing upgrade (line 136) runs unchanged.

Rationale for Origin-first ordering: a CSWSH probe from a malicious page will not have a valid ticket. If we validated the ticket first and then checked Origin, an attacker who has obtained a leaked ticket (from logs, Referer, history, support bundle) could mount a denial-of-service against the legitimate user by burning their tickets with 403 responses. Origin-first means rejected cross-origin attempts do not consume the user's ticket.

3.2 Origin parsing and comparison

• Read the raw Origin header value as a string.
• Strip any trailing /.
• Use a hand-rolled parser (no new dependency) to extract scheme, host, and optional port:
  • scheme must be http or https (lowercased).
  • host must be non-empty and contain no whitespace.
  • port, if present, must parse as u16.
• Apply default-port normalization: https implies port 443; http implies port 80. If the explicit port equals the default for the scheme, drop it from the comparison. This matches browser behavior (browsers do not include default ports in Origin).
• Case-insensitive host comparison; case-sensitive scheme and port.
• Match each configured allowlist entry against the parsed Origin. Exact match only — no subdomain wildcards, no regex, no path.
• If the Origin header is malformed (does not parse) → reject 403 forbidden_origin ("Malformed Origin header").

3.3 Config schema (crates/pm-core/src/config.rs)

Add a new field to SecurityConfig:

/// Allowlist of browser `Origin` values permitted to open the
/// `/api/v1/ws/jobs` WebSocket. Entries are exact `scheme://host[:port]`
/// strings. If empty, the server derives the default from `sso_callback_url`.
#[serde(default = "default_allowed_origins")]
pub allowed_origins: Vec<String>,

Default value (default_allowed_origins): a single-element vector containing the scheme://host[:port] form of sso_callback_url parsed at config-load time. This keeps the default config secure out of the box — a fresh install will only accept WS upgrades from the same origin the SSO callback redirects to.

If sso_callback_url cannot be parsed (e.g., a custom dev value), fall back to vec![] and emit a tracing::warn! at startup. An empty allowlist with no parseable default would make the WS endpoint reject all upgrades; this is the safe direction (fail-closed), but the warning makes it loud.

Add a corresponding ConfigError if allowed_origins is manually set to an empty vector and sso_callback_url is also unparseable, since that combination produces a non-functional WS endpoint. The user must explicitly opt in to "no origins allowed" by providing a list.

3.4 Logging

• On allowed upgrade: existing tracing::info! continues (lines 129–133), augmented with origin = %origin_str for audit context.
• On rejected upgrade: new tracing::warn! with origin = %origin_str and reason = %reason. Never log the ticket value.

3.5 Response shape

Reuse the existing err helper (lines 48–58):

{ "error": { "code": "forbidden_origin", "message": "…" } }

Status: 403 Forbidden for all Origin rejections. Do not differentiate between "missing", "malformed", and "not in allowlist" in the response — they all map to the same code, and the specific reason is logged server-side only.

4. Acceptance Criteria

• A WS upgrade request with a missing Origin header is rejected with 403 and code forbidden_origin. The ticket is not consumed.
• A WS upgrade request with a malformed Origin header is rejected with 403 and code forbidden_origin. The ticket is not consumed.
• A WS upgrade request with an Origin not in the allowlist is rejected with 403 and code forbidden_origin. The ticket is not consumed.
• A WS upgrade request with an allowlisted Origin and a valid, unconsumed ticket succeeds (101 Switching Protocols / upgrade accepted) and the ticket is consumed atomically (existing behavior preserved).
• A WS upgrade request with an allowlisted Origin and an invalid/expired/ already-used ticket is rejected with the existing 401 invalid_ticket / 401 ticket_expired (existing behavior preserved).
• The allowlist is configurable via security.allowed_origins in config/config.example.toml and is documented in that file.
• When allowed_origins is not set, the default is derived from sso_callback_url and the service starts cleanly.
• cargo check and cargo clippy --all-targets pass.
• cargo test -p pm-web passes with the new integration tests added.
• docs/security-review.md documents the new control with an evidence row pointing to crates/pm-web/src/routes/ws.rs.

5. Test Plan

Unit tests in crates/pm-web/src/routes/ws.rs (cfg(test) module) — 33 tests covering the security-critical logic. The end-to-end wiring (HeaderMap extractor, axum handler, response shape) is verified by cargo check, cargo clippy --all-targets, and the manual scripts/integration-test.sh end-to-end check.

Why unit tests instead of tests/ws_origin.rs integration tests: the handler is wired to State<AppState>, and AppState contains a sqlx::PgPool and a pm_ca::CertAuthority that cannot be cheaply constructed in a test (the CA requires a real Postgres connection and on-disk key material, both unavailable in cargo test). Refactoring ws_handler to take a smaller state struct is out of scope for this hardening change.

5.1 pm-core unit tests (crates/pm-core/src/config.rs, 7 tests)

derive_allowed_origins — the sso_callback_url → allowlist derivation:

1. derive_strips_default_https_port — https://x:443/... → https://x
2. derive_keeps_non_default_port — https://x:8443/... → https://x:8443
3. derive_strips_default_http_port — http://x:80/x → http://x
4. derive_handles_trailing_slash — https://x/ → https://x
5. derive_handles_no_path — https://x → https://x
6. derive_returns_empty_for_garbage — rejects "not a url", "", "ftp://x"
7. derive_lowercases_scheme — HTTPS://... → https://...

5.2 pm-web unit tests (crates/pm-web/src/routes/ws.rs, 33 tests)

parse_origin_header (14 tests): basic, with-port, scheme/host lowercasing, path/query/fragment ignored, trailing-slash stripped, empty/whitespace rejected, unsupported schemes rejected, empty host rejected, host with whitespace rejected, malformed port rejected, IPv6 literal rejected, no scheme separator rejected.

Origin::canonical (3 tests): default-port normalization in both directions (http:80, https:443), non-default port kept.

is_origin_allowed (11 tests): exact match, default-port normalization in both directions, case-insensitive host, different host rejected, different scheme rejected, different port rejected, empty allowlist rejected, unparseable allowlist entry rejected, multi-entry allowlist.

check_origin (7 tests): missing header, malformed header, disallowed origin, empty allowlist, allowed origin, default-port normalization allowed, case-insensitive host allowed. This function returns the (StatusCode, Json) error tuple used by the handler, so these tests cover the response shape.

6. Risk Analysis

• Risk: a config that breaks the WS endpoint in production. Mitigation: default is derived from sso_callback_url (already required for SSO to function), and startup logs a warning if the allowlist ends up empty.
• Risk: legitimate cross-origin frontend (e.g., SPA on app.foo.com talking to API on api.foo.com). Out of scope for this fix — the WS endpoint is on the same origin as the SPA. If a future deployment splits them, the operator adds the API origin to allowed_origins. Documented in config/config.example.toml.
• Risk: a non-browser caller (CLI, integration test) cannot connect. Such callers should use the REST API for state mutations; the WS is documented as the browser job-stream channel. If a non-browser WS client is needed, document it in docs/REST_API.md and tell the operator to add its origin.
• Risk: false sense of security. The Origin check is defense-in-depth, not a replacement for the ticket. Documented as such in the security review update.

7. Files Touched

• crates/pm-web/src/routes/ws.rs — handler change.
• crates/pm-core/src/config.rs — new field + default.
• config/config.example.toml — new field documented.
• crates/pm-web/tests/ws_origin.rs — new integration tests (and harness).
• docs/security-review.md — control documentation row.
• tasks/todo.md — plan section (added by the orchestrator).

8. Out of Scope (Future Work)

• Bind ticket issuance to the WS upgrade in a single round-trip (eliminates query-string ticket leakage from logs/history).
• Per-message MAC on WS frames (defense against in-process tampering).
• Rate limiting on the WS endpoint itself.