feat(magic-links): add rate limiting + archirecture documentation

example.env

@@ -382,6 +382,26 @@ OXICLOUD_WOPI_ENABLED=false
 # Example (only addresses on these two domains can be invited):
 #OXICLOUD_EXTERNAL_EMAIL_DOMAINS=partner-a.com,partner-b.io
 
+# Per-sharer rate limit on email-type grants from POST /api/grants. Keyed on
+# the authenticated caller's user_id. Hitting the cap returns 429 with
+# Retry-After. Default 50/hour — generous for legitimate admin invites,
+# protective against a compromised account spamming external users.
+#OXICLOUD_MAGIC_LINK_INVITE_PER_CALLER_PER_HOUR=50
+
+# Per-target-email rate limit on POST /api/auth/magic-link/send. Keyed on
+# the normalised recipient address (lowercased local, punycode domain).
+# Exceeding the cap is silently absorbed (uniform 200 anti-enumeration);
+# audit log records the real reason. Authenticated callers bypass this
+# limit (a logged-in user resending to themselves should not be throttled).
+# Default 5/hour.
+#OXICLOUD_MAGIC_LINK_SEND_PER_EMAIL_PER_HOUR=5
+
+# Per-source-IP backstop on POST /api/auth/magic-link/send. Bounds the cost
+# of one attacker spreading 5/hr requests across many target addresses.
+# Same silently-absorbed behaviour on cap. Honours OXICLOUD_TRUST_PROXY_CIDR
+# for client IP resolution. Default 200/hour.
+#OXICLOUD_MAGIC_LINK_SEND_PER_IP_PER_HOUR=200
+
 # -----------------------------------------------------------------------------
 # PROXY
 # -----------------------------------------------------------------------------