Add passkey configuration and availability policy (inert)

Groundwork for passkey authentication, with the feature switched off by
default and no behaviour change when it is off.

Decision D1: passkeys require central authentication. A passkey is scoped to
a relying party spanning the base domain, which only exists when
SUBDOMAIN_REDIRECT is on and AUTH_SUBDOMAIN resolves to a base domain. The
RP ID is therefore always that base domain, never the request host.

Decision D4: HTTPS is required and is not exemptible. The allowed origin is
built as https://{authSubdomain} from configuration and never from the
request, so an http:// origin cannot be accepted, and isAvailableFor()
additionally refuses to offer the UI on a non-secure connection. The
deprecated setSecuredRelyingPartyId() escape hatch is not used and there is
deliberately no override that could reintroduce one.

Enabling PASSKEY_ENABLED without a usable configuration is a hard error via
a non-optional cache warmer, because entrypoint.sh runs cache:warmup on every
production boot: a misconfigured deployment fails to start instead of
offering a button that cannot work.

Also drops 12 obsolete phpstan-baseline entries for TotpTestHelper: adding
#[\Override] to its anonymous clock removed the rule violation at its source
rather than suppressing it.

Suite: 333 tests / 770 assertions (was 313 / 738), 100% coverage on new
files. phpstan level 6 clean, php-cs-fixer clean, conformance 35/35.

docs/examples/.env.example

@@ -15,6 +15,26 @@
 #SUBDOMAIN_REDIRECT=false   # default disabled, boolean
 #AUTH_SUBDOMAIN=''          # blank, hostname we send user to, to see login page
 
+# --- passkey authentication ---
+# Passkeys (Touch ID / Windows Hello / security keys) as an alternative to TOTP.
+#
+# REQUIRES central authentication (SUBDOMAIN_REDIRECT=true plus AUTH_SUBDOMAIN)
+# and HTTPS. Passkeys are bound to a relying party that spans the base domain,
+# which only exists when central auth is configured; and browsers refuse to run
+# a ceremony over plain HTTP.
+#
+# Enabling this without central auth is a hard error: the container fails at
+# start-up (cache:warmup) rather than offering a passkey button that cannot work.
+#
+# There is deliberately no option to allow an http:// origin, and none to relax
+# the requirement for local development. See the README for the local TLS setup.
+#PASSKEY_ENABLED=false       # default disabled, boolean
+#PASSKEY_RP_NAME=''          # blank to use TITLE
+#PASSKEY_USER_VERIFICATION='required' # required | preferred | discouraged
+#PASSKEY_TIMEOUT=60000       # ceremony timeout in milliseconds
+#PASSKEY_BUTTON_NAME='Sign in with a passkey'
+#PASSKEY_REGISTER_NAME='Register this device as a passkey'
+
 # --- extra options ---
 
 # how long do we allow *ALL* traffic from an ip address after successful login

docs/examples/Caddyfile

@@ -49,10 +49,43 @@ protected.example.com {
 # optionally, if you want to use a subdomain for central preauth
 # set SUBDOMAIN_REDIRECT to true
 # and AUTH_SUBDOMAIN to match the subdomain you use here
+#
+# Passkeys (PASSKEY_ENABLED) require this block AND HTTPS: the ceremony runs
+# here and the credential is scoped to the base domain. Caddy provisions a
+# certificate automatically for a real hostname, so nothing extra is needed in
+# production. This block is also deliberately NOT behind forward_auth — the
+# browser talks to it directly during a ceremony.
 auth.example.com {
 	reverse_proxy preauth
 }
 
+# --- local development with passkeys ---
+# Browsers only allow a WebAuthn ceremony over HTTPS, and preauth does not offer
+# an exemption for http://localhost (that would be a way to run passkeys
+# insecurely in production). So to exercise passkeys locally, give yourself a
+# real hostname and a locally-trusted certificate:
+#
+#   1. Point the names at your machine:
+#        # /etc/hosts
+#        127.0.0.1 auth.preauthtest.local app.preauthtest.local
+#   2. Trust a certificate for them (mkcert installs a local CA):
+#        mkcert auth.preauthtest.local app.preauthtest.local
+#
+#   3. In preauth's .env:
+#        SUBDOMAIN_REDIRECT=true
+#        AUTH_SUBDOMAIN=auth.preauthtest.local
+#        PASSKEY_ENABLED=true
+#
+#   4. Terminate TLS here and proxy to the container:
+#
+# auth.preauthtest.local, "*.preauthtest.local" {
+#     tls /path/to/auth.preauthtest.local+1.pem /path/to/auth.preauthtest.local+1-key.pem
+#     reverse_proxy preauth
+# }
+#
+# Note "localhost" itself cannot be used: it has no base domain, so central
+# auth cannot be configured and passkeys stay disabled.
+
 # --- public rate-limited access (v1.1) ---
 # Configure PUBLIC_PATHS env var to specify which paths are public.
 # Example: PUBLIC_PATHS=/public/**