Oxicloud/example.env

# =============================================================================
# OxiCloud Environment Configuration
# =============================================================================
# Copy this file to .env and modify as needed for your deployment.
#   cp example.env .env
#
# All variables have sensible defaults. Only override what you need.
# =============================================================================

# -----------------------------------------------------------------------------
# SERVER CONFIGURATION
# -----------------------------------------------------------------------------

# Root directory for file storage (default: ./storage)
OXICLOUD_STORAGE_PATH=./storage

# Path to static files directory (default: ./static)
OXICLOUD_STATIC_PATH=./static

# Directory for tier-1 temporary data — pure scratch, safe to lose at reboot.
# Services that need a filesystem path (audio ID3/MP3 duration, video EXIF via
# ffprobe/nom-exif, etc.) stream blobs here from the active backend before
# handing the path to the extractor. The file is auto-removed after each use.
#
# Default: system tempdir (`std::env::temp_dir()`, honours $TMPDIR / $TMP).
# On Linux `/tmp` is often mounted as tmpfs (RAM-backed); high-concurrency
# production deployments concerned about RAM should point this at a
# disk-backed dir (e.g. /var/lib/oxicloud/tmp).
#OXICLOUD_TEMP_DIR=/var/lib/oxicloud/tmp

# Server port (default: 8086)
OXICLOUD_SERVER_PORT=8086

# Server bind address (default: 127.0.0.1)
# Use 0.0.0.0 to bind to all interfaces in Docker
# IPv6 format allowed, either ::1 or [::1]
OXICLOUD_SERVER_HOST=127.0.0.1

# Public base URL for generating share links and external URLs
# If not set, defaults to http://{OXICLOUD_SERVER_HOST}:{OXICLOUD_SERVER_PORT}
# Authentication fails if this is not set and you access the host remotely via a domain
# Example: https://cloud.example.com
#OXICLOUD_BASE_URL=https://cloud.example.com

# ── Upload size caps ──────────────────────────────────────────────────
# See docs/config/storage-fine-tuning.md for sizing guidance.

# Whole-file size ceiling. Applies to BOTH direct PUTs (per-request body)
# and chunked uploads (declared `total_size` at session creation — checked
# upfront so oversized requests never accumulate chunks on disk).
# Default: 10 GB on 64-bit, 1 GB on 32-bit.
#OXICLOUD_MAX_UPLOAD_SIZE=10737418240

# Per-request cap for non-chunked PUT bodies (`POST /api/files/upload`,
# `PUT /webdav/...`, `PUT /remote.php/dav/files/...`). Set below
# MAX_UPLOAD_SIZE so files larger than this are pushed onto the chunked
# protocol (resumable on failure, bounded per-request by CHUNK_MAX_BYTES).
# Default: 1 GiB.
#OXICLOUD_DIRECT_PUT_MAX_BYTES=1073741824

# Per-chunk cap for a single chunked-upload PUT (PATCH /api/uploads/{id}
# or PUT /dav/uploads/.../chunk). NC desktop and the OxiCloud frontend
# split large files into chunks of this size or smaller, so this knob
# tightly bounds the worst-case per-request memory/disk footprint
# independently of the whole-file cap. Default: 100 MB.
#OXICLOUD_CHUNK_MAX_BYTES=104857600

# ── Upload spool directories ─────────────────────────────────────────
# Direct (non-chunked) uploads stream straight into the blob store —
# no spool directory. Only chunked-upload sessions accumulate on disk.
# See docs/config/storage-fine-tuning.md for layout examples.

# Root directory for chunked-upload sessions (REST + NextCloud chunked
# share this root). Default: {STORAGE_PATH}/.uploads. Avoid tmpfs in
# containers (parts count against the cgroup memory limit); NVMe
# placement accelerates chunk PUTs and the /complete streaming pass.
#OXICLOUD_CHUNK_DIR=/var/lib/oxicloud/.uploads

# How often (seconds) the background sweep reconciles each user's cached
# storage usage with the real sum of their files (default: 600 = 10 min).
# GET /api/auth/me serves the cached value instead of recomputing per request;
# this sweep keeps it fresh for deletes/trash too. Lower = fresher quota,
# higher = less background DB work. Minimum enforced: 30s.
#OXICLOUD_STORAGE_USAGE_RECONCILE_SECS=600

# Native WebDAV URL segment that returns the drive listing. Sanitized
# by trimming leading/trailing `/` so `/@drive/`, `@drive`, and
# `@drive/` are equivalent. Three deployment modes:
#
#   * Default `@drive` — back-compat with pre-multi-drive clients.
#       /webdav/…                  → caller's default personal drive
#       /webdav/@drive/            → drive listing (per-drive virtual
#                                    folders)
#       /webdav/@drive/<sel>/…     → specific drive by UUID or its
#                                    display name
#
#   * Empty `""` — no default-drive shortcut; `/webdav/` IS the
#     drive listing. Clients must always name the drive.
#       /webdav/                   → drive listing
#       /webdav/<sel>/…            → specific drive
#
#   * Any other string (e.g. `drives`) — same shape as `@drive` but
#     with your chosen segment substituted.
#
# Selector `<sel>` is a drive UUID or the drive's display name. Only
# drives the caller has Read on via role_grants resolve; unknown
# selector and permission denial both return 404 (anti-enumeration).
#OXICLOUD_WEBDAV_DRIVE_LISTING_PREFIX=@drive

# How often (milliseconds) the background job drains storage.tree_etag_dirty
# and bumps folder tree ETags (default: 500). Write paths only enqueue bump
# requests — this is the upper bound on how stale an ancestor folder's ETag
# (WebDAV/NextCloud collection sync signal) can be after a change. Lower =
# fresher sync detection, higher = fewer background UPDATEs. Minimum: 100.
#OXICLOUD_TREE_ETAG_FLUSH_MS=500

# One-time startup migration that converts pre-CDC whole-file blobs (files
# uploaded before chunked dedup landed) into CDC chunk manifests, in the
# background on the maintenance pool. Fixes the legacy penalty where a Range
# read (video seek) reads — and with encryption, DECRYPTS — the entire blob.
# Idempotent; a no-op once no legacy blobs remain. Disable only on metered
# remote backends (S3/Azure egress) where the one-time re-read of every
# legacy blob should be scheduled deliberately, e.g. off-peak.
#OXICLOUD_LEGACY_RECHUNK=true

# Allow multiple processes to bind to the same port (SO_REUSEPORT).
# DISABLED by default — leaving this off means a second accidental instance
# will fail immediately with "address already in use", which is the safe behaviour.
# Enable ONLY when you deliberately run several worker processes in parallel
# (e.g. behind a process supervisor or during a zero-downtime rolling restart).
# Not supported on Windows.
#OXICLOUD_REUSE_PORT=false

# -----------------------------------------------------------------------------
# DATABASE CONFIGURATION
# -----------------------------------------------------------------------------

# PostgreSQL connection string
# Format: postgres://USER:PASSWORD@HOST:PORT/DATABASE
# For Docker: use 'postgres' as the hostname (the docker-compose service name)
# For local development: use 'localhost:5432'
OXICLOUD_DB_CONNECTION_STRING=postgres://postgres:postgres@postgres/oxicloud

# Maximum number of database connections in the pool (default: 20)
#OXICLOUD_DB_MAX_CONNECTIONS=20

# Minimum number of database connections to maintain (default: 5)
#OXICLOUD_DB_MIN_CONNECTIONS=5

# Maximum connections for the maintenance pool (background/batch tasks).
# This pool is isolated from user requests, preventing background operations
# from starving interactive traffic. Default: 5
#OXICLOUD_DB_MAINTENANCE_MAX_CONNECTIONS=5

# Minimum connections for the maintenance pool. Default: 1
#OXICLOUD_DB_MAINTENANCE_MIN_CONNECTIONS=1

# Build-time database URL for SQLx compile-time checks
# Only needed during compilation, not at runtime
DATABASE_URL=postgres://postgres:postgres@localhost:5432/oxicloud

# -----------------------------------------------------------------------------
# AUTHENTICATION CONFIGURATION
# -----------------------------------------------------------------------------

# JWT secret key for signing authentication tokens
# If not set, a secure secret is auto-generated and persisted to
# <STORAGE_PATH>/.jwt_secret so tokens survive container restarts.
# You only need to set this if you want to share the same secret
# across multiple OxiCloud instances or control it externally.
# Generate a custom secret with: openssl rand -hex 32
#OXICLOUD_JWT_SECRET=

# Access token lifetime in seconds (default: 3600 = 1 hour)
#OXICLOUD_ACCESS_TOKEN_EXPIRY_SECS=3600

# 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

# -----------------------------------------------------------------------------
# OPAQUE aPAKE (zero-knowledge password login, RFC 9807)
# -----------------------------------------------------------------------------
# OPAQUE replaces `POST /api/auth/login` with a zero-knowledge exchange:
# the passphrase never leaves the client, not on registration and not on
# login. This is the substrate for later E2EE work.
#
# Phase 0 (this build) ships the primitives only — endpoints are inert
# until `OXICLOUD_OPAQUE_MODE` is set. Leave everything commented for a
# no-op install; OIDC-only and magic-link-only deployments never need to
# touch OPAQUE at all (see the effective-mode downgrade below).

# OPAQUE mode gate. Values: off | migrate | opaque_only
#   off         — endpoints 404. Default. Safe for OIDC-only / magic-link-only.
#   migrate     — endpoints live; legacy `POST /api/auth/login` still accepted.
#   opaque_only — endpoints live; legacy refused for users with an envelope.
# Effective mode is automatically downgraded to `off` when password auth
# is disabled via OXICLOUD_AUTH_METHODS (OPAQUE has nothing to shadow) —
# an audit-channel log line explains why. So enabling this without
# password in OXICLOUD_AUTH_METHODS is a no-op, not a boot error.
#OXICLOUD_OPAQUE_MODE=off

# Persistent OPAQUE server keypair (base64-encoded ServerSetup blob).
# Generated ONCE per deployment; rotating this invalidates every user's
# registration (they'd all be forced to re-register on next login). Only
# required when `OXICLOUD_OPAQUE_MODE != off` AND password auth is
# enabled — otherwise the value is ignored.
#
# Generate on first-time enable:
#   # Docker (recommended for production):
#   docker run --rm ghcr.io/atalayalabs/oxicloud:latest opaque-setup
#   # Or from a source checkout:
#   cargo run --bin opaque-setup
# Both print the base64 value on stdout (guidance on stderr, so shell
# pipelines capture cleanly). Paste the printed line into your env or
# secrets manager. NEVER regenerate — treat it like your JWT secret;
# losing it forces every user to reset their passphrase.
#OXICLOUD_OPAQUE_SERVER_SETUP=

# Client-side Argon2id key-stretching parameters (RFC 9807 KSF).
# These run on the USER'S DEVICE during OPAQUE login/registration —
# distinct from OXICLOUD_HASH_* which runs on the server for the legacy
# password path. Client-side execution means we can afford higher memory
# than the server would (each user pays once for themselves rather than
# the server paying for every concurrent login).
#
# Bumping these does NOT affect existing envelopes; they'd re-mint on
# the user's next password change.
#
# Memory cost in KiB (default: 262144 = 256 MiB)
#OXICLOUD_OPAQUE_KSF_MEMORY_KIB=262144
# Iterations (default: 3)
#OXICLOUD_OPAQUE_KSF_ITERATIONS=3
# Parallelism lanes (default: 4)
#OXICLOUD_OPAQUE_KSF_PARALLELISM=4

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

# Enable/disable authentication system (default: true)
#OXICLOUD_ENABLE_AUTH=true

# Enable per-user storage quotas (default: false)
#OXICLOUD_ENABLE_USER_STORAGE_QUOTAS=false

# Enable file/folder sharing (default: true)
#OXICLOUD_ENABLE_FILE_SHARING=true

# Enable trash/recycle bin functionality (default: true)
#OXICLOUD_ENABLE_TRASH=true

# Background daemon that deletes expired `storage.role_grants` rows.
# The AuthZ engine already filters expired grants out of every
# permission check at read time, so leaving expired rows in place is
# a hygiene issue — not a security one. This purge deletes rows
# whose `expires_at` is more than GRACE_DAYS in the past, preserving
# the audit / support answer to "what happened to my access?" for
# the grace window.
#
# Default: enabled. Recommended grace: >= 15 days.
#OXICLOUD_GRANT_CLEANUP_ENABLED=true
#OXICLOUD_GRANT_CLEANUP_GRACE_DAYS=15
#OXICLOUD_GRANT_CLEANUP_INTERVAL_HOURS=24

# Enable search functionality (default: true)
#OXICLOUD_ENABLE_SEARCH=true

# Full-text content search (embedded Tantivy index over file names AND file
# content: PDF, Office, plain text/code). Indexing runs on the maintenance
# pool, off the request path. (default: true)
#OXICLOUD_ENABLE_CONTENT_SEARCH=true

# Content index directory (default: {OXICLOUD_STORAGE_PATH}/.search-index)
#OXICLOUD_CONTENT_INDEX_DIR=

# Index worker drain cadence in ms — upper bound on how long a new upload
# takes to become content-searchable (default: 1500)
#OXICLOUD_CONTENT_INDEX_FLUSH_MS=1500

# Files larger than this are indexed by name only, no text extraction
# (default: 33554432 = 32 MiB)
#OXICLOUD_CONTENT_INDEX_MAX_FILE_BYTES=33554432

# Cap on extracted text per unique blob fed to the index
# (default: 1048576 = 1 MiB)
#OXICLOUD_CONTENT_INDEX_MAX_TEXT_BYTES=1048576

# 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

# ── People (face recognition) ────────────────────────────────────────────
# Biometric data (GDPR Art. 9) — OFF by default, opt-in per deployment.
# Detects faces and clusters them into people in the photo library.
#
# Requires ALL of:
#   1. a binary built with the `faces-onnx` cargo feature
#      (`cargo build --release --features faces-onnx`),
#   2. OXICLOUD_ENABLE_FACES=true,
#   3. the ONNX Runtime shared library + two operator-provided ONNX models
#      (a SCRFD/RetinaFace detector with 5-point landmarks, and an ArcFace
#      512-d embedder — e.g. InsightFace `buffalo_l`). Models are NOT shipped.
# Without all three, the People pipeline stays inert (no-op analyzer) and the
# server still boots; the People tab stays hidden in the UI.
#OXICLOUD_ENABLE_FACES=false

# Path to libonnxruntime.{so,dylib,dll}. Falls back to ORT_DYLIB_PATH.
# Use the ONNX Runtime build matching this app's `ort` crate (>= 1.24).
#OXICLOUD_FACES_ORT_DYLIB=/opt/onnxruntime/lib/libonnxruntime.so

# Face detector model (SCRFD/RetinaFace, 5-point landmarks).
#OXICLOUD_FACES_DETECTOR_MODEL=/var/lib/oxicloud/models/scrfd_10g_bnkps.onnx

# Face embedder model (ArcFace, 112x112 input -> 512-d output).
#OXICLOUD_FACES_EMBEDDER_MODEL=/var/lib/oxicloud/models/w600k_r50.onnx

# Detector square input size in px (default: 640)
#OXICLOUD_FACES_DET_SIZE=640

# Minimum detector confidence to keep a face, 0..1 (default: 0.5)
#OXICLOUD_FACES_DET_THRESHOLD=0.5

# IoU threshold for non-maximum suppression, 0..1 (default: 0.4)
#OXICLOUD_FACES_NMS_THRESHOLD=0.4

# ONNX Runtime intra-op threads; 0 = let ONNX Runtime decide (default: 0)
#OXICLOUD_FACES_INTRA_THREADS=0

# WASM plugin runtime (Extism). Requires a binary built with the `plugins`
# cargo feature (`cargo run --features plugins`); without that feature these
# vars are inert. Untrusted plugins run sandboxed: no filesystem, no network,
# capped memory, per-invocation timeout. (default: false)
#OXICLOUD_ENABLE_PLUGINS=false

# Directory scanned for plugins at startup; each plugin is a subdirectory with
# a plugin.toml + its .wasm. (default: {OXICLOUD_STORAGE_PATH}/.plugins)
#OXICLOUD_PLUGINS_DIR=

# Per-invocation wall-clock timeout in ms (default: 250)
#OXICLOUD_PLUGIN_TIMEOUT_MS=250

# Max linear memory per plugin instance, in 64 KiB WASM pages (default: 256 = 16 MiB)
#OXICLOUD_PLUGIN_MAX_MEMORY_PAGES=256

# Max serialized event payload handed to a plugin, in bytes (default: 262144 = 256 KiB)
#OXICLOUD_PLUGIN_MAX_INPUT_BYTES=262144

# Max plugin invocations running at once across all plugins. Past this, dispatch
# sheds load (drops the event, audit-logged) so plugins can't starve the shared
# blocking pool. (default: 16)
#OXICLOUD_PLUGIN_MAX_CONCURRENT_INVOCATIONS=16

# Idle window (seconds) after which a plugin's cached compiled module is dropped
# to reclaim memory; the next event recompiles from the on-disk cache. (default: 300)
#OXICLOUD_PLUGIN_CACHE_IDLE_TTL_SECS=300

# Decompressed-byte ceiling enforced while unpacking an install bundle (zip-bomb
# guard; the install route also caps the compressed body at 32 MiB). (default: 67108864 = 64 MiB)
#OXICLOUD_PLUGIN_MAX_BUNDLE_DECOMPRESSED_BYTES=67108864

# Directory for per-plugin structured logs, one subdir per plugin id.
# (default: {OXICLOUD_STORAGE_PATH}/.plugin-logs)
#OXICLOUD_PLUGIN_LOG_DIR=

# Size (bytes) at which a plugin's active events.jsonl rotates into a gzip segment. (default: 5242880 = 5 MiB)
#OXICLOUD_PLUGIN_LOG_MAX_FILE_BYTES=5242880

# Coarse ceiling on rotated .gz segments kept per plugin at write time. (default: 10)
#OXICLOUD_PLUGIN_LOG_MAX_SEGMENTS=10

# Default age (days) past which rotated log segments are pruned by the sweep;
# overridable per plugin in the admin UI. 0 = purge all rotated segments. (default: 30)
#OXICLOUD_PLUGIN_LOG_RETENTION_DAYS=30

# Default aggregate byte cap on kept log segments per plugin (oldest deleted
# first); overridable per plugin. 0 = purge all rotated segments. (default: 268435456 = 256 MiB)
#OXICLOUD_PLUGIN_LOG_TOTAL_MAX_BYTES=268435456

# Bounded depth of the log-write queue; a flood past this sheds the oldest batch
# rather than blocking dispatch or growing RAM. (default: 1024)
#OXICLOUD_PLUGIN_LOG_QUEUE_CAPACITY=1024

# -----------------------------------------------------------------------------
# STORAGE ENTRIES (multi-entry, recommended)
# -----------------------------------------------------------------------------
#
# Declare one or more NAMED storage backends. The one the app runs on is
# picked from the DB (`admin_settings.storage.active_backend_name`) — the
# admin panel's storage tab flips it, and cross-backend migration is a
# recoverable-run job that copies blobs between two entries. See
# `docs/plan/storage-multi-entry.md` for the full model.
#
# Rules:
#   * `OXICLOUD_STORAGE_ENTRIES` is a comma-separated allowlist of names.
#     Names must match `[a-z0-9_-]{1,32}` and be unique. Order is
#     preserved (the first entry is the fallback when no active pointer
#     is set in the DB yet — e.g. fresh install).
#   * For each name `N`, the parser reads
#     `OXICLOUD_STORAGE_<N>_BACKEND` (local | s3 | azure) plus the
#     backend-specific fields below. A missing required field aborts
#     boot with the exact var name in the error message.
#   * `OXICLOUD_STORAGE_<N>_ENCRYPTION_KEY` is a comma-separated LIST
#     of `<cipher>:<key>` pairs. Presence implies encryption is
#     enabled on that entry (no separate enable flag). The LAST pair
#     wins on writes; every pair is a candidate for reads. Supported
#     ciphers: `aes-256-gcm` (default when no cipher prefix is given)
#     and `none` (empty-key sentinel used at pair-list head for a
#     decrypt-in-place rotation, or at tail for an encrypt-in-place
#     rotation). Bad base64 / wrong length / duplicate keys /
#     multiple `none` pairs abort boot with the entry name. See
#     `docs/plan/storage-key-rotation.md` for rotation recipes.
#   * SETTING `_ENTRIES` alongside the legacy flat vars below (e.g.
#     `OXICLOUD_STORAGE_BACKEND` + `OXICLOUD_S3_BUCKET`) is a FAIL-FAST
#     boot error — pick one mode. Migrate any leftover flat vars into
#     per-entry `_STORAGE_<NAME>_*` form.
#
# Example: local disk today, S3 target for a planned migration.
#
#OXICLOUD_STORAGE_ENTRIES=local_main,s3_prod
#
#OXICLOUD_STORAGE_local_main_BACKEND=local
#OXICLOUD_STORAGE_local_main_ROOT_DIR=/srv/oxicloud
#
#OXICLOUD_STORAGE_s3_prod_BACKEND=s3
#OXICLOUD_STORAGE_s3_prod_S3_BUCKET=my-oxicloud-bucket
#OXICLOUD_STORAGE_s3_prod_S3_REGION=us-east-1
#OXICLOUD_STORAGE_s3_prod_S3_ENDPOINT_URL=https://s3.example.com
#OXICLOUD_STORAGE_s3_prod_S3_ACCESS_KEY=
#OXICLOUD_STORAGE_s3_prod_S3_SECRET_KEY=
#OXICLOUD_STORAGE_s3_prod_S3_FORCE_PATH_STYLE=false
#OXICLOUD_STORAGE_s3_prod_ENCRYPTION_KEY=aes-256-gcm:  # generate: openssl rand -base64 32
# The bare shorthand `<base64 key>` (no `aes-256-gcm:` prefix)
# also works; the explicit form makes the cipher visible and is
# required once you have more than one pair in the list.
#
# Two-pair rotation example (paste both pairs in .env, restart,
# then trigger the format-upgrade job, then drop the OLD pair):
#OXICLOUD_STORAGE_s3_prod_ENCRYPTION_KEY=aes-256-gcm:<OLD_KEY>,aes-256-gcm:<NEW_KEY>
#
# Repair flag: if you rename an entry in .env while the DB still points
# at the old name, boot aborts with an actionable error pointing at:
#
#   oxicloud --select-storage <name>
#
# which verifies the entry exists in `_ENTRIES` and updates the DB
# pointer without booting the server. See §Fallback in the plan doc.

# -----------------------------------------------------------------------------
# STORAGE BACKEND — DEPRECATED (single-backend flat vars)
# -----------------------------------------------------------------------------
#
# ⚠️ DEPRECATED. Use the STORAGE ENTRIES section above for new deployments.
# These flat variables still work when `OXICLOUD_STORAGE_ENTRIES` is UNSET —
# the parser then synthesises a single entry named `default` from them AND
# emits a boot-time deprecation warning
# (`storage.legacy_flat_vars_deprecated`) so operators see it in logs.
# Removal target: not yet fixed. Migrate at your convenience by moving
# each `OXICLOUD_STORAGE_BACKEND` / `OXICLOUD_S3_*` / `OXICLOUD_AZURE_*` /
# `OXICLOUD_STORAGE_ENCRYPTION_*` into `OXICLOUD_STORAGE_<NAME>_*` under
# an entry declared in `OXICLOUD_STORAGE_ENTRIES`.

# 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 --- DEPRECATED (per-entry key is the new home)
# AES-256-GCM encryption applied to blobs before writing to any backend.
# WARNING: losing the key means losing all data. Back it up securely.
#
# ⚠️ DEPRECATED. Prefer per-entry `OXICLOUD_STORAGE_<NAME>_ENCRYPTION_KEY`
# under an entry declared in `OXICLOUD_STORAGE_ENTRIES` (see the top
# multi-entry section). The flat vars below still work in
# zero-entries mode and get folded into the synthesised `default`
# entry, alongside a deprecation warning at boot.

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

# Enable OIDC authentication (default: false)
OXICLOUD_OIDC_ENABLED=false

# OIDC provider issuer URL (required if OIDC enabled)
# Example: https://auth.example.com/application/o/oxicloud/
#OXICLOUD_OIDC_ISSUER_URL=

# OIDC client ID (required if OIDC enabled)
#OXICLOUD_OIDC_CLIENT_ID=

# OIDC client secret (required if OIDC enabled)
#OXICLOUD_OIDC_CLIENT_SECRET=

# Callback URL after OIDC authentication (must match IdP config)
# Default: http://localhost:8086/api/auth/oidc/callback
#OXICLOUD_OIDC_REDIRECT_URI=http://localhost:8086/api/auth/oidc/callback

# OIDC scopes to request (default: openid profile email)
#OXICLOUD_OIDC_SCOPES=openid profile email

# Frontend URL to redirect after successful OIDC login
# Default: http://localhost:8086
#OXICLOUD_OIDC_FRONTEND_URL=http://localhost:8086

# Auto-create users on first OIDC login (JIT provisioning) (default: true)
#OXICLOUD_OIDC_AUTO_PROVISION=true

# Comma-separated list of OIDC groups that grant admin role
# Example: admins,cloud-admins
#OXICLOUD_OIDC_ADMIN_GROUPS=

# DEPRECATED: prefer OXICLOUD_AUTH_METHODS=oidc (with optional
# OXICLOUD_AUTH_POLICIES=auto_redirect_if_standalone_oidc for the
# server-side /login redirect). This flag still works but emits a
# boot warning; removal is planned for the next major release.
#
# Legacy path — disables password-based login entirely when OIDC is
# active (default: false).
#OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=false

# Display name for the OIDC provider shown in UI (default: SSO)
#OXICLOUD_OIDC_PROVIDER_NAME=SSO

# -----------------------------------------------------------------------------
# WOPI (WEB APPLICATION OPEN PLATFORM INTERFACE) CONFIGURATION
# -----------------------------------------------------------------------------

# Enable WOPI integration for office document editing (default: false)
# Used with Collabora, OnlyOffice, or other WOPI-compatible editors
OXICLOUD_WOPI_ENABLED=false

# URL to the WOPI client's discovery endpoint
# Example for Collabora: http://collabora:9980/hosting/discovery
# Example for OnlyOffice: http://onlyoffice/hosting/discovery
#OXICLOUD_WOPI_DISCOVERY_URL=

# Public OxiCloud URL used by the browser for the WOPI host page.
# Keep this on the OxiCloud hostname, even when OnlyOffice/Collabora runs elsewhere.
# Example: https://cloud.example.com
#OXICLOUD_WOPI_PUBLIC_BASE_URL=

# Optional callback URL the editor uses to reach OxiCloud's /wopi/* endpoints.
# Set this only when the editor uses a different internal address than the browser.
# Example: http://oxicloud:8086
#OXICLOUD_WOPI_BASE_URL=

# Secret key for signing WOPI access tokens
# Falls back to OXICLOUD_JWT_SECRET if not set
#OXICLOUD_WOPI_SECRET=

# WOPI access token lifetime in seconds (default: 86400 = 24 hours)
#OXICLOUD_WOPI_TOKEN_TTL_SECS=86400

# 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

# -----------------------------------------------------------------------------
# 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.
#
# OxiCloud does NOT spool mail or retry failed sends — each delivery is a
# single attempt. For durability against brief upstream outages, point this
# at a local MTA (Postfix, OpenSMTPD, msmtp-mta, …) configured as a
# smarthost. The local MTA owns the queue and retries against your real
# relay. See docs/config/env.md → "Reliability and retries" for the recipe.

# 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

# Allowlist of email domains accepted on the public POST /api/auth/register
# endpoint. Comma-separated, case-insensitive, exact-match on the post-`@`
# part of the address. Empty (the default) = any domain is allowed.
#
# DISTINCT from OXICLOUD_EXTERNAL_EMAIL_DOMAINS above: this one gates
# SELF-registration (a stranger signing up), while the external list
# gates INVITATIONS (an admin/user sharing to an outside address).
# An operator can, for example, keep public sign-up locked to their
# own company domain while allowing invitations to any customer:
#   OXICLOUD_REGISTRATION_ALLOWED_EMAIL_DOMAINS=mycompany.com
#   OXICLOUD_EXTERNAL_EMAIL_DOMAINS=            (empty)
#
# Wildcards / subdomain semantics are intentionally NOT supported:
# `mycompany.com` does not match `eng.mycompany.com`. List every subdomain
# explicitly when needed.
#
# Rejected registrations return HTTP 403 with error code
# `RegistrationDomainNotAllowed` and log an `audit` line with
# reason=domain_not_allowed for operator visibility.
#
# Example (only staff at these two domains can self-register):
#OXICLOUD_REGISTRATION_ALLOWED_EMAIL_DOMAINS=mycompany.com,mycompany-eu.com

# ---------------------------------------------------------------------------
# OXICLOUD_AUTH_METHODS — authentication method allowlist.
# ---------------------------------------------------------------------------
# Comma-separated list of `password`, `magic_link`, and/or `oidc`. Controls
# which authentication methods this deployment offers on the login page
# and accepts at the corresponding endpoints.
#
# FAIL-FAST semantics — misconfiguration crashes the server at boot with
# a specific error, never silently degrades:
#   * Unknown token (e.g. `password,sso2`) → panic on startup
#   * Empty allowlist (e.g. `OXICLOUD_AUTH_METHODS=`) → panic
#   * `oidc` in the list but `OXICLOUD_OIDC_ENABLED != true` → panic
#     ("advertising a login method the server can't serve")
#
# LOOSE SEMANTIC (documented) — the reverse of the last bullet is NOT
# fatal today: when this list is explicitly set WITHOUT `oidc` but
# `OXICLOUD_OIDC_ENABLED=true`, OIDC is served in addition to the
# listed methods. The enabled flag wins. A warning is logged at boot
# telling the admin to reconcile. This will escalate to a fail-fast
# panic in the next major release — align configs now to avoid the
# breaking change.
#
# Semantics per configuration:
#   * Unset                                   — permissive default
#                                               (password + magic_link;
#                                               OIDC gated by its own flag).
#   * `password`                              — password login only.
#   * `magic_link`                            — magic-link login only
#                                               (requires SMTP; see gate below).
#   * `oidc`                                  — OIDC only, no local login.
#                                               Cleanest "SSO-only" posture.
#   * `password,oidc`                         — hybrid: local + SSO,
#                                               no magic-link.
#   * `password,magic_link,oidc`              — everything on.
#
# SECURITY — startup gate. When `magic_link` is the ONLY working method
# (no `password`, no `oidc`) but no SMTP transport is configured, the
# server refuses to start. Prevents silently locking every user out.
#
# SECURITY — OIDC master rule. When OIDC is enabled (either explicitly
# in this list or via `OXICLOUD_OIDC_ENABLED=true`), magic-link login is
# HARD-disabled regardless of what this list says. OIDC is the master
# identity provider; magic-link would sidestep any 2FA / step-up the
# IdP enforces.
#
# DEPRECATED alias: `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=true` still
# removes `password` from this list but emits a boot warning; it will be
# removed in the next major release. New deployments MUST use this
# `OXICLOUD_AUTH_METHODS` env var instead.
#
# Default (when unset): password + magic_link.
#OXICLOUD_AUTH_METHODS=password,magic_link
#OXICLOUD_AUTH_METHODS=oidc                  # OIDC-only (needs OIDC_ENABLED=true)
#OXICLOUD_AUTH_METHODS=password,oidc         # hybrid local + SSO

# ---------------------------------------------------------------------------
# OXICLOUD_REQUIRE_VERIFIED_EMAIL — gate login on email verification.
# ---------------------------------------------------------------------------
# When `true`, `POST /api/auth/login` returns 403 `EmailNotVerified` for
# any account whose `email_verified_at` is NULL. Users can prove control
# by requesting a magic-link (whose redemption stamps
# `email_verified_at`) — so this composes naturally with `magic_link` in
# the allowlist above to give users a self-service verification path.
#
# Admin-created (`POST /api/admin/users`) and first-run setup-admin
# (`POST /api/setup`) users are auto-verified — admin fiat counts as
# verification. OIDC-JIT users are also stamped verified at creation.
#
# Default: false
#OXICLOUD_REQUIRE_VERIFIED_EMAIL=false

# 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

# ---------------------------------------------------------------------------
# OXICLOUD_AUTH_POLICIES — additive auth-policy switches (comma-separated).
# ---------------------------------------------------------------------------
# Each recognised token grants an exception or restriction to the default
# auth behaviour. Empty (unset) = pure defaults. Vector shape so future
# policies can be added without new env vars.
#
# Recognised tokens:
#
#   permit_magic_link_for_password_users
#     Allow magic-link sign-in for accounts that ALSO have a password.
#     Off by default — magic-link would otherwise weaken the password to
#     mailbox-strength. Aligns with modern SaaS UX (Slack, Notion, etc.)
#     when set. OIDC-linked users are ALWAYS rejected regardless of this
#     policy — the IdP is the security boundary and may enforce MFA we
#     shouldn't bypass.
#
#   auto_redirect_if_standalone_oidc
#     When OIDC is the ONLY working login method (no password, no
#     magic-link, whether via the allowlist or the OIDC-master rule),
#     the login SPA auto-redirects to the OIDC authorize endpoint on
#     page load instead of showing a click-to-continue SSO button.
#     Off by default because auto-redirect can loop on IdP failure
#     (login → IdP error → back to login → auto-redirect again) and
#     makes logout-then-visit-login flows feel broken (bounces the
#     user right back into the app). Silent no-op when the login page
#     has more than one method available (nothing to auto-choose).
#
# Example:
#OXICLOUD_AUTH_POLICIES=permit_magic_link_for_password_users
#OXICLOUD_AUTH_POLICIES=auto_redirect_if_standalone_oidc
#OXICLOUD_AUTH_POLICIES=permit_magic_link_for_password_users,auto_redirect_if_standalone_oidc


# Operator-level kill switch for share-notification emails to internal
# users (the "Alice shared 'Project Alpha' with you" mail that fires when
# `magic_link_eligibility` rejects the recipient — typically password
# users and OIDC users with a known email). When `true` (default), the
# new RecipientNotificationService dispatches plain-notification mail
# on every share. When `false`, internal users discover new shares only
# at next login.
#
# This is a coarser knob than the per-user
# `auth.users.notify_on_share` column (set via the profile "Email me
# when someone shares with me" checkbox): when this env is `false`,
# the per-user opt-in does not matter.
#
# External-user magic-link FIRST-invitations are NOT affected by this
# flag — those always send, because the link is the only way the
# recipient can claim the share for the first time. Subsequent shares
# to an existing external follow the same plain-notification path and
# are subject to both this knob and the per-user opt-out.
#OXICLOUD_NOTIFY_INTERNAL_USERS_ON_SHARE=true

# -----------------------------------------------------------------------------
# INTERNATIONALIZATION (server-rendered surfaces)
# -----------------------------------------------------------------------------
#
# Default locale for server-rendered HTML pages and outbound emails when
# no stronger signal is available. The resolution priority is:
#
#   HTML pages (anonymous, e.g. magic-link landing):
#     1. ?lang=xx query override
#     2. browser Accept-Language header (q-weighted)
#     3. this default
#
#   Emails to a known user:
#     1. user.preferred_locale column
#     2. this default
#
# Supported locales are discovered at boot by listing static/locales/*.json,
# so adding a 17th locale is a file-drop operation (no rebuild required).
# This variable must match one of the discovered codes — startup fails fast
# if you set OXICLOUD_DEFAULT_LOCALE=xx and no static/locales/xx.json exists.
#
# Default: "en". Today's shipped locales: ar, de, en, es, fa, fr, hi, it,
# ja, ko, nl, pl, pt, ru, zh, zh-TW.
#OXICLOUD_DEFAULT_LOCALE=en

# -----------------------------------------------------------------------------
# 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)
# -----------------------------------------------------------------------------
# OxiCloud uses mimalloc as its global memory allocator for performance.
# By default, mimalloc RETAINS freed memory in internal free-lists instead of
# returning it to the operating system. This causes the process RSS to grow
# over time (e.g., after large file uploads or password hashing) and never
# shrink back — even though the application has already freed that memory.
#
# In containerized / memory-constrained environments (Docker, K8s, VPS with
# limited RAM), this is critical: without these settings, the container can
# appear to "leak" hundreds of MiB that are actually just retained by the
# allocator.
#
# These variables are read directly by the mimalloc C library at startup.
# They are NOT OxiCloud-specific — they are part of mimalloc's official API.
# Docs: https://microsoft.github.io/mimalloc/environment.html

# MIMALLOC_PURGE_DELAY: Delay (in ms) before freed memory is returned to the OS.
#   0  = return immediately (RECOMMENDED for Docker / limited RAM)
#   -1 = never return (maximum performance, highest RAM usage)
#   10 = mimalloc default (slight delay for reuse optimization)
# Setting this to 0 can reduce idle RAM by 80-120 MiB in typical deployments.
MIMALLOC_PURGE_DELAY=0

# MIMALLOC_ALLOW_LARGE_OS_PAGES: Use 2 MiB huge pages for allocations.
#   0 = disabled (RECOMMENDED for Docker — avoids RSS inflation from THP)
#   1 = enabled (better TLB performance on bare-metal servers with plenty of RAM)
# 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