Security

oriel is a read-only viewer for a local folder — built for a personal machine, an SSH tunnel, or a trusted LAN behind a reverse proxy, not a hardened internet-facing service. Understand the model before exposing it.

The full policy is in SECURITY.md; this is the short version.

What it protects

• Read-only. No write, upload, or mutation endpoints — requests can only read.
• Path scoping. Every request must fall under a served prefix (prose dirs, the figure root, plugin extra_prefixes); anything else is 404. Resolved paths are checked to stay within the served root, so .. climbs and symlinks pointing outside the tree are refused. A hostile URL can't wander into .env.
• Access key. Unless --no-auth, every request needs a secret key (?key=…, then an HttpOnly cookie), stored at ~/.oriel/token (mode 600), compared in constant time.

What it does not protect against

• Sniffing / MITM. Traffic is plain HTTP. The key deters other local/LAN users; it does not stop anyone observing the network. Beyond localhost, put it behind TLS (reverse proxy) or an SSH tunnel / Tailscale.
• Key leakage via URL. The ?key=… bootstrap URL can land in shell or browser history or a Referer. Treat it as a bearer token; the cookie is the steady state.
• Untrusted folders. A folder's oriel_plugins.py is executed — the same trust level as running its code. Never serve a folder you wouldn't run.

Recommendations

• Keep the bind on 127.0.0.1 (default). Reach a remote instance over ssh -L 18787:localhost:18787 <server>, not --host 0.0.0.0.
• If you must expose it, terminate TLS and add auth at a reverse proxy; keep the oriel key on as defense in depth.
• Only serve folders you trust.

Back to the overview.