doc: update example.env and docs/config/env.md

example.env

@@ -30,6 +30,9 @@ OXICLOUD_SERVER_HOST=127.0.0.1
 # Example: https://cloud.example.com
 #OXICLOUD_BASE_URL=https://cloud.example.com
 
+# Maximum upload size in bytes (default: 10 GB on 64-bit)
+#OXICLOUD_MAX_UPLOAD_SIZE=10737418240
+
 # -----------------------------------------------------------------------------
 # DATABASE CONFIGURATION
 # -----------------------------------------------------------------------------
@@ -48,8 +51,7 @@ OXICLOUD_DB_CONNECTION_STRING=postgres://postgres:postgres@postgres/oxicloud
 
 # Maximum connections for the maintenance pool (background/batch tasks).
 # This pool is isolated from user requests, preventing background operations
-# (verify_integrity, garbage_collect, storage recalculation) from starving
-# interactive traffic. Default: 5
+# from starving interactive traffic. Default: 5
 #OXICLOUD_DB_MAINTENANCE_MAX_CONNECTIONS=5
 
 # Minimum connections for the maintenance pool. Default: 1
@@ -74,8 +76,43 @@ DATABASE_URL=postgres://postgres:postgres@localhost:5432/oxicloud
 # Access token lifetime in seconds (default: 3600 = 1 hour)
 #OXICLOUD_ACCESS_TOKEN_EXPIRY_SECS=3600
 
-# Refresh token lifetime in seconds (default: 2592000 = 30 days)
-#OXICLOUD_REFRESH_TOKEN_EXPIRY_SECS=2592000
+# Refresh token lifetime in seconds (default: 604800 = 7 days)
+# Active sessions auto-renew on use via token rotation, so users stay logged in
+# as long as they interact within this window.
+#OXICLOUD_REFRESH_TOKEN_EXPIRY_SECS=604800
+
+# Argon2id password hashing parameters
+# Increase memory cost for stronger hashing at the expense of login latency.
+# Memory cost is in KiB (default: 65536 = 64 MiB)
+#OXICLOUD_HASH_MEMORY_COST=65536
+# Number of iterations (default: 3)
+#OXICLOUD_HASH_TIME_COST=3
+# Parallelism lanes (default: 2)
+#OXICLOUD_HASH_PARALLELISM=2
+
+# -----------------------------------------------------------------------------
+# RATE LIMITING & ACCOUNT LOCKOUT
+# -----------------------------------------------------------------------------
+
+# Max login attempts per IP before rate-limiting kicks in (default: 10)
+#OXICLOUD_RATE_LIMIT_LOGIN_MAX=10
+# Rate-limit window for logins in seconds (default: 60)
+#OXICLOUD_RATE_LIMIT_LOGIN_WINDOW_SECS=60
+
+# Max registration attempts per IP per window (default: 5)
+#OXICLOUD_RATE_LIMIT_REGISTER_MAX=5
+# Rate-limit window for registrations in seconds (default: 3600)
+#OXICLOUD_RATE_LIMIT_REGISTER_WINDOW_SECS=3600
+
+# Max token refresh attempts per IP per window (default: 20)
+#OXICLOUD_RATE_LIMIT_REFRESH_MAX=20
+# Rate-limit window for token refresh in seconds (default: 60)
+#OXICLOUD_RATE_LIMIT_REFRESH_WINDOW_SECS=60
+
+# Consecutive failed logins before account lockout (default: 5)
+#OXICLOUD_LOCKOUT_MAX_FAILURES=5
+# Account lockout duration in seconds (default: 900 = 15 minutes)
+#OXICLOUD_LOCKOUT_DURATION_SECS=900
 
 # -----------------------------------------------------------------------------
 # FEATURE FLAGS
@@ -96,6 +133,85 @@ DATABASE_URL=postgres://postgres:postgres@localhost:5432/oxicloud
 # Enable search functionality (default: true)
 #OXICLOUD_ENABLE_SEARCH=true
 
+# Enable music playlists and audio metadata (default: true)
+#OXICLOUD_ENABLE_MUSIC=true
+
+# Expose other OxiCloud users as a read-only "system" address book
+# at GET /api/address-books (default: true)
+# Set to false to prevent users from browsing the user directory.
+#OXICLOUD_EXPOSE_SYSTEM_USERS=true
+
+# -----------------------------------------------------------------------------
+# STORAGE BACKEND
+# -----------------------------------------------------------------------------
+
+# Blob storage backend: local (default), s3, or azure
+#OXICLOUD_STORAGE_BACKEND=local
+
+# --- S3-Compatible (AWS S3, Backblaze B2, Cloudflare R2, MinIO) ---
+# Used when OXICLOUD_STORAGE_BACKEND=s3
+
+# S3 bucket name (required)
+#OXICLOUD_S3_BUCKET=my-oxicloud-bucket
+
+# AWS region (default: us-east-1)
+#OXICLOUD_S3_REGION=us-east-1
+
+# Access credentials
+#OXICLOUD_S3_ACCESS_KEY=
+#OXICLOUD_S3_SECRET_KEY=
+
+# Custom endpoint for non-AWS providers (e.g. MinIO, R2, B2)
+#OXICLOUD_S3_ENDPOINT_URL=https://s3.example.com
+
+# Force path-style URLs — required for MinIO, Cloudflare R2 (default: false)
+#OXICLOUD_S3_FORCE_PATH_STYLE=false
+
+# --- Azure Blob Storage ---
+# Used when OXICLOUD_STORAGE_BACKEND=azure
+
+# Storage account name (required)
+#OXICLOUD_AZURE_ACCOUNT_NAME=
+# Storage account key (or use SAS token below)
+#OXICLOUD_AZURE_ACCOUNT_KEY=
+# Blob container name (required)
+#OXICLOUD_AZURE_CONTAINER=oxicloud
+# SAS token (alternative to account key)
+#OXICLOUD_AZURE_SAS_TOKEN=
+
+# --- Local Disk Cache for Remote Backends ---
+# LRU cache that speeds up repeated reads from S3 or Azure.
+
+# Enable disk cache (default: false)
+#OXICLOUD_STORAGE_CACHE_ENABLED=false
+# Maximum cache size in bytes (default: 53687091200 = 50 GB)
+#OXICLOUD_STORAGE_CACHE_MAX_SIZE=53687091200
+# Cache directory (default: {STORAGE_PATH}/.blob-cache)
+#OXICLOUD_STORAGE_CACHE_PATH=
+
+# --- Client-Side Encryption ---
+# AES-256-GCM encryption applied to blobs before writing to any backend.
+# WARNING: losing the key means losing all data. Back it up securely.
+
+# Enable at-rest blob encryption (default: false)
+#OXICLOUD_STORAGE_ENCRYPTION_ENABLED=false
+# Base64-encoded 32-byte key; generate with: openssl rand -base64 32
+#OXICLOUD_STORAGE_ENCRYPTION_KEY=
+
+# --- Retry Policy (Remote Backends) ---
+# Exponential backoff retries for transient errors on S3 and Azure.
+
+# Enable retry (default: true)
+#OXICLOUD_STORAGE_RETRY_ENABLED=true
+# Maximum number of retry attempts (default: 3)
+#OXICLOUD_STORAGE_RETRY_MAX_RETRIES=3
+# Initial backoff in milliseconds (default: 100)
+#OXICLOUD_STORAGE_RETRY_INITIAL_BACKOFF_MS=100
+# Maximum backoff cap in milliseconds (default: 10000)
+#OXICLOUD_STORAGE_RETRY_MAX_BACKOFF_MS=10000
+# Backoff multiplier per retry (default: 2.0)
+#OXICLOUD_STORAGE_RETRY_BACKOFF_MULTIPLIER=2.0
+
 # -----------------------------------------------------------------------------
 # OPENID CONNECT (OIDC) / SSO CONFIGURATION
 # -----------------------------------------------------------------------------
@@ -170,6 +286,37 @@ OXICLOUD_WOPI_ENABLED=false
 # WOPI lock expiration in seconds (default: 1800 = 30 minutes)
 #OXICLOUD_WOPI_LOCK_TTL_SECS=1800
 
+# -----------------------------------------------------------------------------
+# NEXTCLOUD COMPATIBILITY
+# -----------------------------------------------------------------------------
+# Enables the Nextcloud-compatible API layer for clients that speak the
+# Nextcloud protocol (desktop sync, mobile apps, Nextcloud Talk, etc.)
+
+# Enable Nextcloud compatibility (default: false)
+#OXICLOUD_NEXTCLOUD_ENABLED=false
+
+# Instance ID suffix used in oc:id formatting (default: ocnca)
+#OXICLOUD_NEXTCLOUD_INSTANCE_ID=ocnca
+
+# Emulated Nextcloud version reported to clients (default: 28.0.4)
+# Clients use this to decide which protocol features to enable.
+#OXICLOUD_NEXTCLOUD_VERSION=28.0.4
+
+# -----------------------------------------------------------------------------
+# PROXY
+# -----------------------------------------------------------------------------
+
+# Use this section if you are running OxiCloud behind a reverse proxy.
+
+# Trusted Proxy CIDRs — comma-separated list of CIDR blocks whose
+# X-Forwarded-For / X-Real-IP headers will be trusted for client IP detection.
+# Leave unset if OxiCloud is directly exposed (no proxy).
+# Example: 127.0.0.1/32,10.0.0.0/8,172.16.0.0/12,::1/128
+#OXICLOUD_TRUST_PROXY_CIDR=
+
+# DEPRECATED — use OXICLOUD_TRUST_PROXY_CIDR instead
+#OXICLOUD_TRUST_PROXY_HEADERS=
+
 # -----------------------------------------------------------------------------
 # MEMORY ALLOCATOR TUNING (IMPORTANT FOR RAM USAGE)
 # -----------------------------------------------------------------------------
@@ -201,16 +348,3 @@ MIMALLOC_PURGE_DELAY=0
 # When enabled with Linux Transparent Huge Pages (THP), partially-used 2 MiB
 # pages inflate the reported RSS by up to 20-30 MiB.
 MIMALLOC_ALLOW_LARGE_OS_PAGES=0
-
-# -----------------------------------------------------------------------------
-# PROXY
-# -----------------------------------------------------------------------------
-
-# Use this section if you are running OxiCloud behind a proxy
-
-# Trusted Proxy IPs. Format: coma separated list of CIDR
-# (default not defined = server without proxy)
-# if defined and proxy's IPs match, client_ip will be defined from
-# `X-Forwarded-For` / `X-Real-Ip`
-#OXICLOUD_TRUST_PROXY_CIDR=192.168.0.1/32,10.1.2.0/24
-