.env.example

# =============================================================================
# Kesh — Configuration template (.env.example)
# =============================================================================
#
# Copier ce fichier vers `.env` et adapter chaque placeholder `<GENERATE_ME: ...>`
# et `<EDIT: ...>`. Story 10-1 : les defaults insecure type `changeme` ou
# `change-me-32-bytes-...` font fail-fast au boot — aucune valeur ne doit
# rester telle quelle en production.
#
# `.env` est ignoré par git (`.gitignore:14`). `.env.example` reste committé.

# =============================================================================
# Variables Kesh (consommées par crates/kesh-api/src/config.rs)
# =============================================================================

# --- Base de données ---
# URL de connexion MariaDB 10.11+. Sur Synology DSM, pointer vers le hostname
# du service MariaDB sur le réseau Docker externe `frontend` (cf. docker-compose.prod.yml).
# Si MariaDB tourne sur l'hôte NAS via Package Center DSM et que le réseau
# Docker n'a pas accès direct, utiliser l'IP LAN du NAS au lieu du hostname.
DATABASE_URL=<EDIT: mysql://kesh:<password>@<mariadb-host>:3306/kesh>

# --- Application ---
# Port HTTP du serveur kesh-api (défaut 80, URL standard sans suffixe :port).
KESH_PORT=80
# KESH_HOST volontairement non défini ici — le compose prod le force à 0.0.0.0
# (bind interne Docker, AC #8 Story 10-1). Pour dev hors Docker, set explicitement
# KESH_HOST=127.0.0.1 dans votre .env local. ATTENTION : KESH_TEST_MODE=true
# exige un bind loopback (127.0.0.1 / ::1 / localhost).
#
# --- Conflit port 80 (Synology DSM Web Station / autre service / dev local) ---
# Le port 80 par défaut peut entrer en conflit avec un service existant sur l'hôte
# (DSM Web Station, nginx local, IIS, etc.). 4 options d'override possibles, à
# choisir selon votre contexte de déploiement :
#
#   (a) Garder le port applicatif 80 mais remapper côté host via compose :
#       Dans docker-compose.{prod,dev}.yml, changer le mapping `"127.0.0.1:80:80"`
#       vers `"127.0.0.1:8080:80"` (ou tout autre HOST_PORT libre). L'application
#       reste sur 80 côté container, accessible via http://localhost:8080.
#
#   (b) Changer le port applicatif lui-même :
#       Décommenter `KESH_PORT=3000` ci-dessous ET aligner le mapping compose
#       sur `"127.0.0.1:3000:3000"`. URL d'accès : http://localhost:3000.
#       # KESH_PORT=3000
#
#   (c) Container sur une IP dédiée (Docker macvlan/ipvlan) :
#       Configurer le container avec sa propre IP via réseau macvlan ; le mapping
#       host devient inutile (le container répond directement sur son IP:80).
#       Procédure détaillée : voir manuel admin section « Changer le port d'écoute ».
#
#   (d) Dev `cargo run` natif (hors Docker) sur Linux non-root :
#       Linux non-root ne peut PAS bind un port <1024 (security feature).
#       Set OBLIGATOIREMENT KESH_PORT=3000 (ou ≥ 1024) dans votre .env local :
#       # KESH_PORT=3000
#       Alternatives : (i) lancer `cargo run` avec `sudo` (déconseillé), (ii)
#       ajouter la capability via `sudo setcap 'cap_net_bind_service=+ep' target/debug/kesh-api`.

# --- Compte admin initial (Story v011-5 — double-usage) ---
#
# Ces variables sont OPTIONNELLES depuis v0.1.2. Deux usages possibles :
#
# 1. BOOTSTRAP DÉCLARATIF (DB vide au 1er boot) : si les vars sont renseignées,
#    l'admin est créé automatiquement au boot. Pratique pour CI/Test/déploiements
#    automatisés. Retirer les vars après le 1er boot réussi.
#
# 2. ONBOARDING SELF-SERVICE (DB vide au 1er boot, vars NON renseignées) : Kesh
#    crée seulement une company stub. L'écran `/setup` au 1er accès web crée
#    le compte admin via formulaire. Recommandé pour installations interactives.
#
# 3. RECOVERY BREAK-GLASS (DB avec admin existant, vars renseignées avec un
#    mot de passe DIFFÉRENT du hash actuel) : reset le password de l'admin
#    correspondant au username. Procédure de récupération en cas d'oubli.
#    Voir manuel admin section « J'ai oublié mon mot de passe administrateur ».
#
# Contraintes si vars renseignées : password ≥ 12 chars, ≠ "changeme" (case-
# insensitive). Générer un password fort : openssl rand -base64 24
#
# ⚠️ Restreindre les permissions du .env : chmod 600 .env (le password en clair
#    permet le recovery, donc accès au compte admin).
#
#KESH_ADMIN_USERNAME=admin
#KESH_ADMIN_PASSWORD=<GENERATE_ME: openssl rand -base64 24>

# --- Authentification (Story 1.5) ---
# OBLIGATOIRE en production. Minimum 32 caractères ET ne doit pas contenir
# "change-me" sinon fail-fast Story 10-1.
# Générer via : openssl rand -hex 32  (produit 32 bytes = 256 bits encodés en 64 chars hex)
KESH_JWT_SECRET=<GENERATE_ME: openssl rand -hex 32>
# Durée de vie de l'access token JWT en minutes (défaut 15, borne 1-1440)
KESH_JWT_EXPIRY_MINUTES=15
# Lifetime absolu du refresh token en jours (défaut 30, borne 1-365)
KESH_REFRESH_TOKEN_MAX_LIFETIME_DAYS=30

# --- Cookies session (v0.1.3 hotfix Issue #136) ---
#
# Le backend émet les cookies session (`kesh_access_token`, `kesh_refresh_token`)
# avec le flag `Secure` par défaut → le browser refuse de les stocker/envoyer
# sur une connexion HTTP non-TLS. C'est le bon défaut sécurité pour toute
# instance accessible via HTTPS (reverse proxy Let's Encrypt, certificat
# Synology DSM, etc.).
#
# **Pour les déploiements LAN strict HTTP-only** (e.g. NAS privé sur domaine
# RFC 8375 `*.home.arpa` derrière un Traefik en HTTP, dev local pur sans
# certificat), passer à `false` pour permettre aux cookies de fonctionner
# sans HTTPS. ⚠️ Cookies session deviennent alors sniffables sur tout
# réseau intermédiaire (LAN privé compris) — NE JAMAIS activer en prod
# exposée Internet sans HTTPS.
#
# Valeurs acceptées : `true` / `1` (défaut, sécurisé) ou `false` / `0`
# (override HTTP-only). Tout autre valeur (`True`, `yes`, `on`, espaces...)
# refuse le démarrage avec ConfigError::InvalidCookieSecureValue.
#
# Alternative recommandée : mettre HTTPS via reverse proxy (Let's Encrypt
# automatique si domaine public, certificat auto-signé `mkcert` si LAN
# privé sans domaine externe).
KESH_COOKIE_SECURE=true

# --- Session & Rate Limiting (Story 1.6) ---
# Sliding expiration : durée d'inactivité avant expiration du refresh token (défaut 15, borne 1-1440)
KESH_REFRESH_INACTIVITY_MINUTES=15
# Rate limiting sur /api/v1/auth/login : fenêtre de comptage en minutes (défaut 15, borne 1-1440)
KESH_RATE_LIMIT_WINDOW_MINUTES=15
# Rate limiting : nombre max de tentatives échouées par IP dans la fenêtre (défaut 5, borne 1-100)
KESH_RATE_LIMIT_MAX_ATTEMPTS=5
# Rate limiting : durée de blocage en minutes après dépassement du seuil (défaut 30, borne 1-1440)
KESH_RATE_LIMIT_BLOCK_MINUTES=30

# --- Localisation (FR75) ---
# Locale par défaut de l'interface : fr / de / it / en (défaut fr).
KESH_LANG=fr

# --- Politique mot de passe utilisateur (FR6) ---
# Longueur minimum pour les passwords des users créés via UI (défaut 12,
# borne 8-128). Distinct du KESH_ADMIN_PASSWORD 12 chars seedé via env.
KESH_PASSWORD_MIN_LENGTH=12

# --- Import bancaire (Story 8-1b — CAMT.053) ---
# Taille max upload bank-import en MiB binaire (1 MiB = 1024² bytes).
# Borne [1, 100]. Hors plage → fallback sur défaut 10.
KESH_BANK_IMPORT_MAX_MB=10

# --- Export / import d'installation (.keshbackup) ---
# Plafond d'assemblage in-memory de l'export complet (MiB). Au-delà, la réponse
# est spillée vers un fichier temporaire et streamée. Borne [1, 2048], défaut 50.
#KESH_ADMIN_EXPORT_INMEM_MB=50
# Taille max d'un upload .keshbackup à l'import (MiB). Borne [1, 10240], défaut 512.
#KESH_ADMIN_IMPORT_MAX_MB=512
# Répertoire du backup automatique pré-import (filet avant restore destructeur).
# Défaut /tmp — PERDU au redémarrage du conteneur ; monter un volume persistant.
#KESH_ADMIN_BACKUP_DIR=/data/backup

# --- Chemins internes (rarement modifiés, Docker) ---
# Répertoire du SPA compilé servi en fallback.
#KESH_STATIC_DIR=frontend/build
# Répertoire des fichiers de traduction (FTL).
#KESH_LOCALES_DIR=locales

# --- Import de factures depuis un dossier (Story 12-5, #194) ---
# Kesh peut importer des factures fournisseurs (PDF/image porteurs d'un Swiss QR
# Code) déposées dans un dossier surveillé, décoder le QR côté serveur et créer
# des factures « à compléter ». Les deux dossiers ci-dessous DOIVENT être montés
# en volumes persistants (cf. docker-compose) — PAS /tmp (perte au redémarrage).
#
# Dossier d'archivage des justificatifs (copies des fichiers importés, hors DB,
# nommées {sha256}.{ext}). Défaut /data/documents.
#KESH_DOCUMENTS_DIR=/data/documents
# Dossier inbox scruté à l'import. Déposez-y vos fichiers ; les fichiers traités
# avec succès en sont supprimés (la copie archivée fait foi), les échecs sont
# déplacés dans <inbox>/failed/. Défaut /data/inbox.
#KESH_INBOX_DIR=/data/inbox
#
# --- Chemins HOST des bind mounts (docker-compose) ---
# Pour rendre l'inbox accessible depuis votre PC (SMB / Synology Drive), montez
# ces dossiers sur un dossier PARTAGÉ du NAS. Synology : créez un dossier partagé
# (ex. « kesh ») avec sous-dossiers inbox/ et documents/, puis :
#KESH_INBOX_HOST_DIR=/volume1/kesh/inbox
#KESH_DOCUMENTS_HOST_DIR=/volume1/kesh/documents
# (défauts dev sans .env : ./inbox et ./documents dans le dossier du projet)
# Taille max d'un fichier inbox en octets (défaut 25 Mo = 26214400).
#KESH_INBOX_MAX_FILE_BYTES=26214400
# Nombre max de fichiers traités par déclenchement d'import (défaut 200).
#KESH_INBOX_MAX_FILES_PER_RUN=200
# Nombre max de pages PDF rendues par fichier (anti-DoS pdfium, défaut 20).
#KESH_INBOX_MAX_PDF_PAGES=20

# --- Logging ---
# Niveau de log Rust : trace / debug / info / warn / error (défaut info).
# ATTENTION : en `debug`/`trace`, la couche SQL (sqlx) journalise potentiellement
# le texte complet de chaque requête AVEC ses valeurs. Pour éviter de déverser des
# données métier en clair sur disque, Kesh maintient une baseline `sqlx=warn` même
# quand RUST_LOG passe à `debug`. Pour obtenir malgré tout le SQL (diagnostic),
# ciblez explicitement sqlx : `RUST_LOG=debug,sqlx=debug` — à éviter en production
# et sur données réelles.
RUST_LOG=info

# --- Logs fichier avec rotation (Story v011-1, Issue #119) ---
# EN PLUS de stdout/`docker logs`, kesh-api écrit ses logs dans un fichier avec
# rotation native. ACTIVÉ par défaut via docker-compose.yml ET .prod.yml
# (mount ./log:/var/log/kesh + KESH_LOG_FILE_PATH=/var/log/kesh/kesh.log).
#
# Chemin HOST du répertoire de logs (bind mount docker-compose). Pointe vers un
# dossier partagé du NAS pour consulter les logs depuis le PC (SMB/Drive) :
#KESH_LOG_HOST_DIR=/volume1/kesh/log
# (défaut sans .env : ./log dans le dossier du projet)
#
# Chemin complet du fichier de log. VIDE ou absent → logs fichier désactivés
# (stdout uniquement, comportement v0.1.0).
# KESH_LOG_FILE_PATH=/var/log/kesh/kesh.log
#
# Rotation : daily / hourly / never (défaut daily). Valeur inconnue → daily.
# KESH_LOG_FILE_ROTATION=daily
#
# Nombre de fichiers de log conservés (défaut 7). IGNORÉ si rotation=never
# (fichier unique jamais élagué). 0 ou non-numérique → fallback 7.
# KESH_LOG_FILE_MAX_FILES=7
#
# Format : pretty (lisible) / json (ingestion outillée). Défaut pretty.
# KESH_LOG_FILE_FORMAT=pretty
#
# ATTENTION PERMISSIONS (Synology / Docker) : le container kesh-api tourne en
# root → le répertoire ./log et ses fichiers seront owned root:root côté hôte
# NAS. Hyper Backup (qui tourne en root) les lit sans problème. Si vous
# consultez les logs via un user non-root, utilisez sudo (`sudo tail -f
# ./log/kesh.log`) ou ajustez les permissions du répertoire.

# --- E-mails sortants / SMTP (Story 17-4 #122, Story 20-3b1 #224) ---
# La config SMTP sert à DEUX fonctions indépendantes :
#  1. Envoi de factures par e-mail (PDF QR-facture joint) — activé dès que
#     les 4 vars KESH_SMTP_HOST/USER/PASSWORD/FROM sont renseignées (visible
#     via le champ smtpConfigured de /health). Sans SMTP, le bouton d'envoi
#     est simplement indisponible (aucun impact sur le reste).
#  2. Recovery self-service : lien de réinitialisation envoyé par email
#     (valable 30 min, usage unique). DÉSACTIVÉ par défaut ; exige EN PLUS
#     KESH_FEATURE_FORGOT_PASSWORD=true et KESH_PUBLIC_BASE_URL. Si non
#     configuré, le seul recours reste le break-glass admin KESH_ADMIN_RESET
#     (cf. section compte admin ci-dessus + manuel administrateur).
#
# FAIL-FAST : si KESH_FEATURE_FORGOT_PASSWORD=true, les 5 vars KESH_SMTP_HOST,
# KESH_SMTP_USER, KESH_SMTP_PASSWORD, KESH_SMTP_FROM et KESH_PUBLIC_BASE_URL
# doivent être renseignées, sinon le serveur refuse de démarrer (message
# listant les vars manquantes). L'envoi de factures seul (sans recovery) ne
# fail-fast jamais : SMTP incomplet = fonction indisponible, boot normal.
# KESH_SMTP_PORT et KESH_SMTP_TLS ont des défauts (587 / true) et peuvent
# rester commentées.
#KESH_FEATURE_FORGOT_PASSWORD=true
#
# Serveur SMTP sortant. Gmail : smtp.gmail.com + mot de passe d'application.
#KESH_SMTP_HOST=<EDIT: smtp.example.com>
# Port SMTP (défaut 587, STARTTLS).
#KESH_SMTP_PORT=587
#KESH_SMTP_USER=<EDIT: noreply@example.com>
# ⚠️ SECRET — jamais loggé par Kesh ; protéger ce fichier (chmod 600 .env).
#KESH_SMTP_PASSWORD=<EDIT: mot-de-passe-smtp>
# Adresse expéditrice de TOUS les e-mails Kesh (reset + factures). Adresse
# simple sans display-name — pour les factures, le nom de votre société est
# ajouté automatiquement à l'envoi, et le Reply-To pointe vers l'e-mail de
# la société s'il est renseigné (Réglages).
#KESH_SMTP_FROM=<EDIT: noreply@example.com>
# STARTTLS (défaut true). ⚠️ false = identifiants SMTP et liens secrets
# transitent EN CLAIR — uniquement pour un relais local de confiance.
#KESH_SMTP_TLS=true
#
# URL publique de l'instance, SANS slash final — sert à construire le lien
# {base}/reset-password?token=... envoyé par email.
#KESH_PUBLIC_BASE_URL=<EDIT: https://kesh.example.ch>

# --- KESH_TEST_MODE (DO NOT SET IN PRODUCTION) ---
# DO NOT SET KESH_TEST_MODE IN PRODUCTION — réservé exclusivement aux tests
# intégrés CI/dev. L'activation en prod désactive des garde-fous sécurité
# (bind loopback obligatoire, accès endpoints /api/v1/_test/*, etc.).
# Volontairement absent de ce template.

# --- Onboarding reset gate (KF-002 / Story 7-1) ---
# Permet l'endpoint POST /api/v1/onboarding/reset au-delà de step 2 quand
# is_demo=true. NE PAS définir en production : un admin avec un is_demo
# corrompu en base pourrait alors wipe une instance déployée.
# Ne définir que sur les déploiements de démo (sandbox, training).
# Valeurs acceptées (case-insensitive) : "1", "true", "yes". Tout autre valeur ou unset = bloqué.
# KESH_PRODUCTION_RESET=

# =============================================================================
# Service MariaDB bundled (DEV ONLY — docker-compose.yml + docker-compose.dev.yml)
# =============================================================================
#
# Ces variables sont consommées par les composes dev (`docker-compose.yml` et
# `docker-compose.dev.yml`) qui démarrent un service MariaDB en sidecar pour
# le développement local. **PAS UTILISÉES par docker-compose.prod.yml** —
# en prod, MariaDB est fournie par l'utilisateur (Package Center DSM ou
# autre) et configurée via `DATABASE_URL` ci-dessus.

MARIADB_ROOT_PASSWORD=kesh_dev_root
MARIADB_DATABASE=kesh
MARIADB_USER=kesh
MARIADB_PASSWORD=kesh_dev