doc: add OXICLOUD_SMTP_* variables + external variables user options

example.env

@@ -311,6 +311,71 @@ OXICLOUD_WOPI_ENABLED=false
 # Clients use this to decide which protocol features to enable.
 #OXICLOUD_NEXTCLOUD_VERSION=28.0.4
 
+# -----------------------------------------------------------------------------
+# OUTBOUND EMAIL (SMTP)
+# -----------------------------------------------------------------------------
+#
+# Used by the magic-link invitation flow (sharing with someone by email) and
+# the login-via-email flow. When HOST is empty (the default), the feature is
+# disabled and any endpoint that needs email returns 503.
+
+# SMTP server hostname or IP. Empty = feature disabled.
+#OXICLOUD_SMTP_HOST=smtp.example.com
+
+# Submission port. Common values:
+#   587 = STARTTLS submission (default)
+#   465 = implicit TLS submission
+#    25 = plain relay (development only)
+#OXICLOUD_SMTP_PORT=587
+
+# SASL username for SMTP AUTH. Leave empty for anonymous relay.
+#OXICLOUD_SMTP_USER=oxicloud@example.com
+
+# SASL password. Logged as `<set>` / `<anon>` in startup banner (never echoed
+# in plaintext).
+#OXICLOUD_SMTP_PASS=
+
+# `From:` mailbox. Either a bare address or RFC 5322 name-address form.
+#OXICLOUD_SMTP_FROM=OxiCloud <noreply@example.com>
+
+# Transport encryption mode:
+#   starttls = port 587 with STARTTLS upgrade (default — recommended)
+#   tls      = implicit TLS from the first byte (port 465)
+#   none     = no encryption; emits a startup WARN, development only
+#OXICLOUD_SMTP_TLS=starttls
+
+# -----------------------------------------------------------------------------
+# MAGIC-LINK AUTHENTICATION
+# -----------------------------------------------------------------------------
+#
+# Knobs for the invite-by-email / login-via-email flows. Both rely on SMTP
+# being configured above.
+
+# Lifetime of a freshly-minted magic-link token, in hours. After this, the
+# background sweeper marks the token expired. Must be > 0.
+#OXICLOUD_MAGIC_LINK_TTL_HOURS=24
+
+# Kill switch for the whole magic-link flow.
+#   true  = POST /api/grants accepts `subject.type = "email"`; new external
+#           users are created lazily and invitation mails are sent.
+#   false = the same call returns 403; POST /api/auth/magic-link/send
+#           returns the uniform stub response without issuing a token.
+# This is the coarse "turn it all off" switch; the per-domain allowlist
+# below is the fine-grained version.
+#OXICLOUD_ALLOW_EXTERNAL_USERS=true
+
+# Allowlist of email domains accepted when minting a new external user.
+# Comma-separated, case-insensitive, exact-match on the post-`@` part of the
+# address. Empty (the default) = any domain is allowed, subject to
+# OXICLOUD_ALLOW_EXTERNAL_USERS above.
+#
+# Wildcards / subdomain semantics are intentionally NOT supported:
+# `partner.com` does not match `eng.partner.com`. List every subdomain
+# explicitly when needed.
+#
+# Example (only addresses on these two domains can be invited):
+#OXICLOUD_EXTERNAL_EMAIL_DOMAINS=partner-a.com,partner-b.io
+
 # -----------------------------------------------------------------------------
 # PROXY
 # -----------------------------------------------------------------------------