| 1 | # tunnel_origins.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own origin normalization for Remote Control tunnel URLs and CSRF/WebSocket same-origin checks. |
| 6 | - Provide a small helper boundary between tunnel discovery and security enforcement. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - `tunnel_origins.py` owns the runtime implementation. |
| 11 | - `tunnel_origins.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. |
| 12 | - Top-level functions: |
| 13 | - `origin_from_url(value)` |
| 14 | - `origin_key(value)` |
| 15 | - `get_active_tunnel_origins()` |
| 16 | |
| 17 | ## Runtime Contracts |
| 18 | |
| 19 | - Normalize URL and Origin header values to `scheme://host[:port]`, omitting default ports. |
| 20 | - Return comparable origin keys with default ports restored for same-origin checks. |
| 21 | - Treat invalid, missing, or malformed origins as `None`. |
| 22 | - Discover active tunnel origins from `TunnelManager` and the Docker tunnel API without raising if either source is unavailable. |
| 23 | - Keep tunnel service lookups short-timeout and local-only. |
| 24 | |
| 25 | ## Work Guidance |
| 26 | |
| 27 | - Keep parsing based on `urllib.parse` rather than hand-rolled string checks. |
| 28 | - Preserve defensive exception handling because tunnel services are optional and may not be running. |
| 29 | - Coordinate security-sensitive changes with CSRF and WebSocket tests. |
| 30 | |
| 31 | ## Verification |
| 32 | |
| 33 | - Run `pytest tests/test_csrf_tunnel_origins.py tests/test_ws_csrf.py -q` after changing tunnel origin behavior. |
| 34 | |
| 35 | ## Child DOX Index |
| 36 | |
| 37 | No child DOX files. |