docs: own the un-guard procedure and the browser-only law

AGENTS.md states the three exposure postures and why the guard chain cannot front a
non-browser client. Infrastructure/Caddy.md gains *Unguard a vhost* — route first,
IdP rows last, audit lists after — since deleting the proxy provider while traffic
still enters :8016 hands browsers authentik's error page. The Audiobookshelf page
retires its two-doors law (the guarded vhost as a browser-only door, remote
listening via VPN) for one address every client carries, adds how a listener gets an
account, and says plainly what the exemption costs.
This commit is contained in:
dank committed 2026-11-03 01:54:08 -08:00
1 parent aa57c1a894
commit 882a9f6808
3 files changed
+119 -24

No files matched your search

+16 -3
View File
@@ -227,9 +227,18 @@ See `serverAppConfigs-docs/Architecture/Testing Policy.md`.
## External Exposure Policy (MANDATORY)
Every Caddy-proxied service is either behind the auth chain (Anubis :8923 →
Authentik embedded outpost) or explicitly internal-only — no public DNS name,
no vhost. New services default to internal-only until guarded.
Every Caddy-proxied service is in exactly one of three postures: behind the
auth chain (Anubis :8923 → Authentik embedded outpost), **exempt by
construction** because it authenticates itself (`auth.`, git smart-HTTP, Gitea,
OpenWebUI, Jellyfin, Plex, Audiobookshelf, the *arr stack), or internal-only —
no public DNS name, no vhost. New services default to internal-only until guarded.
The guard chain is a **browser-only device**: Anubis demands a JavaScript
proof-of-work and the outpost works from a session cookie, so any non-browser
client — a native app, a podcast RSS reader, an OPDS client, `git`, a
service-to-service call — is answered with challenge HTML where it expected
JSON or a socket payload. A service that must serve such a client cannot sit
behind the chain; it has to own its authentication.
When guarding a new vhost — provider first, then route:
@@ -248,6 +257,10 @@ When guarding a new vhost — provider first, then route:
Exempt categories (document the reason in the vhost comment): the IdP itself
(`auth.`), git smart-HTTP endpoints, services with their own complete auth.
Unguarding a vhost is the mirror image of the procedure above — the route flips
first and the IdP rows go last — and `serverAppConfigs-docs/Infrastructure/Caddy.md`
*Unguard a vhost* owns the steps.
## Deletion & Trash Policy (MANDATORY)
Never `rm`. Move deletions into trash so they stay recoverable: