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.

### Passkeys (WebAuthn)

Off by default (`PASSKEY_ENABLED=0`). When on, the following hold:

- **Registration requires a valid TOTP code.** The checkbox rides on an
  ordinary login submission, and the code check in that same request is what
  authorises the ceremony. There is no enrolment token, no CLI path, and no way
  to create a credential without already holding the secret. The identity comes
  from the authenticated session, never from the request body.
- **The challenge is server-authoritative and single-use.** It is generated and
  stored server-side; the client's copy is never trusted. The stored record is
  deleted *before* verification runs, so a failed or replayed attempt cannot be
  retried against the same challenge. Records live in the in-memory `nonceCache`
  with a 300-second TTL and deliberately do not survive a restart.
- **Only the derived origin is accepted.** The allowed origin is always
  `https://{AUTH_SUBDOMAIN}`, computed from configuration and never from the
  request. `http://` is therefore rejected regardless of how the request
  arrived, and there is no setting that re-enables it. The library's deprecated
  `setSecuredRelyingPartyId()` escape hatch is not used, and development uses
  real TLS instead of an exemption.
- **The RP ID is the base domain**, so a credential is scoped to every service
  on that domain. This is the intended behaviour and the reason central auth is
  a hard prerequisite: without a single shared domain there is no sane RP ID.
- **Failures are indistinguishable.** An unknown credential, a bad signature
  and a wrong origin all produce the same response as a wrong TOTP code, so the
  endpoint cannot be used to enumerate credentials.
- **Failures share the login rate-limit budget.** A failed ceremony costs the
  same token as a wrong code, and once the limit is reached every method is
  blocked. Passkeys cannot be used to sidestep a lockout, and the resource guard
  that bounds ceremony *starts* is deliberately separate, so a legitimate login
  never spends failure budget.
- **The signature counter is not a security control.** Most passkeys —
  anything synchronised through a keychain — report a constant counter, so a
  counter-based clone check would lock users out of their own credentials.
  preauth accepts an unchanged counter and rejects only one that moves
  *backwards*, which is the only signal the value can carry. **Clone detection is
  deliberately not a property this feature claims.**
- **Attestation is deliberately not requested** (`attestation: 'none'`).
  Attestation conveyance is only a preference a client may ignore, and the FIDO
  metadata service is bypassed both by the zero AAGUID that privacy-preserving
  passkeys already send and by self attestation — while still refusing
  legitimate authenticators newer than its cached blob. This was measured rather
  than assumed; see §2.3 of
  `docs/passkey-auth-subdomain-plan.md` for the evidence. **Revisit if** a
  deployment needs to prove which make and model of authenticator is enrolled,
  or if a policy (rather than a preference) requires attested keys — in which
  case the metadata service must be pinned and kept current, and the zero-AAGUID
  case decided explicitly rather than by omission.
- **The ceremony replies are not cacheable.** They are the only 2xx this
  application returns straight to a browser (every other 2xx is consumed by the
  proxy's `forward_auth` check), so they carry the same anti-caching headers as
  the rest of the login flow.

## 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.