From 0b03399c1a36f9b6f761f56ba306a21074d52e46 Mon Sep 17 00:00:00 2001
From: Jonas Miederer <jonas.miederer@fau.de>
Date: Sun, 27 Sep 2026 09:14:57 +0200
Subject: [PATCH] chore: LLM provider env for Langflow, persistent sessions,
 Fernet key doc

---
 .env.example | 24 +++++++++++++++++++++++-
 CHANGELOG.md | 11 +++++++++++
 README.md    |  6 +++++-
 3 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/.env.example b/.env.example
index 66225d5..40e3dbe 100644
--- a/.env.example
+++ b/.env.example
@@ -17,6 +17,11 @@ LANGFLOW_SUPERUSER=langflow
 # Long random values (check_prod.py enforces length). Never leave the
 # placeholders: the authoring UI is internet-facing.
 LANGFLOW_SUPERUSER_PASSWORD=
+# MUST be a valid Fernet key (44 chars, urlsafe-base64, 32 bytes) — any
+# other value breaks variable decryption ("Fernet key must be 32
+# url-safe base64-encoded bytes") and provider keys cannot be saved.
+# Generate with:
+#   python -c "import base64,os;print(base64.urlsafe_b64encode(os.urandom(32)).decode())"
 LANGFLOW_SECRET_KEY=
 # Single static key; validated against env (LANGFLOW_API_KEY_SOURCE=env), superuser scope.
 LANGFLOW_API_KEY=sk-
@@ -51,4 +56,21 @@ SMTP_USERNAME=
 SMTP_PASSWORD=
 
 # --- LLM (optional; tests mock the provider without it) ---
-# LLM_API_KEY=
\ No newline at end of file
+# LLM_API_KEY=
+
+# --- LLM provider für Langflow (Authoring-UI + LFX-Runtime) ---
+# Langflow erzeugt daraus automatisch Global Variables (Credential-Typ);
+# LFX liest dieselben Werte zur Laufzeit. Eine in der UI angelegte Global
+# Variable mit gleichem Namen hat Vorrang, die Env-Variable ist Fallback.
+# OpenAI-kompatibler Endpoint (auch selbst gehostet); ohne eigenen Provider
+# leer lassen. Beispiel: https://openrouter.ai/api/v1
+OPENAI_API_KEY=
+OPENAI_BASE_URL=
+
+# --- Langflow-Login-Sitzung ---
+# Refresh-Token-Gültigkeit in Sekunden (Default 604800 = 7 Tage).
+# 7776000 = 90 Tage: einmal einloggen, Container-Restarts übersteht die
+# Session, solange LANGFLOW_SECRET_KEY stabil bleibt. In Prod kürzer wählen.
+# LANGFLOW_REFRESH_TOKEN_EXPIRE_SECONDS=7776000
+# Erstellt Global Variables aus Env (Credential-Typ), restart-fest:
+# LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT=OPENAI_API_KEY,OPENAI_BASE_URL
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae63868..2ace98a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   automatisch (Report mit `pulled`-Liste). Der Hintergrund-Beobachter und der
   Startup-Sync bleiben dateibasiert. Die Verwaltung zeigt eine deutsche
   Schritt-Anleitung direkt beim Sync-Button.
+- LLM-Provider-Umgebung für Langflow: `OPENAI_API_KEY` + `OPENAI_BASE_URL`
+  in `.env` (OpenAI-kompatible Endpoints) erzeugen automatisch
+  restart-feste Global Variables in Langflow; LFX liest dieselben Werte.
+- Langflow-Sitzungen halten länger: `LANGFLOW_REFRESH_TOKEN_EXPIRE_SECONDS`
+  (Default weiter 7 Tage, Dev-Beispiel 90) + stabile JWT-Signatur via
+  `LANGFLOW_SECRET_KEY` — kein Re-Login nach Container-Restarts.
 ### Fixed
 - Flow-Sync aus Langflow: neue Flows blieben unsichtbar, weil LFX-Uploads
   mit `Permission denied` scheiterten (named Volume root-owned, LFX läuft
@@ -25,6 +31,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   0o600-Dateien, die Langflow beim Start abstürzen ließen
   (`Permission denied` in `/app/flows`, Crash-Loop) und der API Fehler
   (`unreadable`) verursachten.
+- `LANGFLOW_SECRET_KEY` muss ein gültiger Fernet-Key sein (44 Zeichen,
+  urlsafe-base64): ein Hex-String brach die Variablen-Verschlüsselung mit
+  `Fernet key must be 32 url-safe base64-encoded bytes` (500 beim Anlegen
+  von Global Variables — Provider-Keys ließen sich nicht speichern).
+  `.env.example` dokumentiert die Erzeugung.
 - LFX runtime user gets a home directory (`useradd -m`, `HOME` set):
   without one every flow run failed with "Settings service not found".
 ### Security
diff --git a/README.md b/README.md
index 0fca6c9..1c09b1c 100644
--- a/README.md
+++ b/README.md
@@ -89,7 +89,11 @@ a database server. Postgres can return later by changing `DATABASE_URL`
 
 `.env` holds only ubiquitous variables (identical value in dev and prod:
 secrets, service URLs). Dev-only variables travel via `devcontainer.json`
-(`APP_ENV=dev`); paths resolve from the repo root in code.
+(`APP_ENV=dev`); paths resolve from the repo root in code. LLM provider
+keys for Langflow are plain env vars (`OPENAI_API_KEY`,
+`OPENAI_BASE_URL`) — Langflow turns them into restart-proof global
+variables, LFX reads them at runtime. `LANGFLOW_SECRET_KEY` must be a
+valid Fernet key (see `.env.example`).
 
 ## Getting Started