preauth/SECURITY.md

Security Policy

Supported Versions

Version	Supported
unreleased (v1 development)	✅

Reporting a Vulnerability

Report vulnerabilities privately to security@digitaladapt.com (or open a private security advisory on the repository). Please include reproduction steps and affected versions. You will receive an acknowledgement within 48 hours and a status update at least weekly until resolution.

Do not open a public issue for a suspected vulnerability. preauth is an authentication gateway — it sits in front of every protected service, so a weakness here is a weakness everywhere behind it.

Security model summary

preauth implements the auth half of the forward_auth pattern: a reverse proxy calls it per request to decide whether a request may reach the upstream service.

• Two outcomes per request: allow or intercept. AcceptListener / RejectListener / InterceptListener decide, and the decision is made on every request rather than cached — a cached auth session is an anti-pattern (GUIDING-LIGHT §3.3d), which is also why this project gets no service worker.
• The login flow is never cached. The login page, failed logins, redirects and rate-limit responses are sent with Cache-Control: no-cache, no-store, must-revalidate, proxy-revalidate, max-age=0, s-maxage=0. An aggressive cache (notably older Safari) replaying a stale pre-auth response presents to the user as being logged back out after a refresh.
• Headers are set by the app, not left to the proxy. X-Content-Type-Options: nosniff, X-Frame-Options: DENY, a Content-Security-Policy, and Strict-Transport-Security: max-age=31536000. Docs recommend mirroring the caching headers at the edge as defence in depth, but the app does not depend on it.
• TOTP is required. Secrets come from TOTP_URI; if it is unset the app generates one and prints it for enrolment. Login state is carried in a signed payload (src/Data/Payload.php) bound to a nonce and a scope, not in a server-side session store.
• Rate limiting is on by default, with the block response configurable (TEAPOT=false returns 429 rather than 418).
• REMOTE_USER is trusted input, not a secret. In remote_user modes the gateway accepts an upstream-asserted identity, so the upstream must be the only path to the app. Do not expose preauth directly to the internet for this mode.
• .env is never committed; secrets are env vars injected at runtime. Real secrets belong in .env.local or bin/console secrets:set, read via %env(...)%. .env.example and .env.test are the committed env files.

Scope

In scope: the application code in src/, the shipped Caddyfile, the Dockerfile, and anything that affects the allow/intercept decision.

Out of scope: the forward_auth integration at the edge (a host-proxy configuration concern, see docs/examples/Caddyfile) and the security of the services preauth protects.

Deployment note

preauth runs as a container and drops privileges via USER (Guiding Light §6.4): the image runs as the non-root app user (uid/gid 1000) and owns the state paths it needs. Only /data is written at runtime — the cache pools behind sessions, backup codes and rate limiting — and /config is declared because the base image points Caddy's XDG config dir there. If you pin a different user: in your compose file, that user must be able to write to both paths — otherwise login state and backup codes cannot be persisted.