Secrets & .env

Wo API-Tokens, Passwörter und andere Secrets hingehören.

#Secrets & .env

API-Tokens, OAuth-Secrets und Datenbank-Passwörter werden nicht in apis.php oder anderen Config-Dateien gehalten, sondern in einer separaten .env-Datei pro Tenant.

#Warum

• apis.php und Tool-Configs werden gelegentlich an ein LLM weitergegeben (Tool-Definition, Knowledge-Search-Ergebnisse). Klartext-Tokens hätten dort nichts zu suchen.
• Bei tm pull / tm sync reisen Config-Dateien zwischen deinem Rechner und dem Server — Tokens nicht mit.
• Key-Rotation soll ohne Code-Änderung gehen.

#Architektur

In API-Configs und Tool-Headern referenzierst du Tokens über den Marker {{secret:KEY}}:

'apis' => [
    'shop_api' => [
        'base_url' => 'https://shop.example.com/api/v2/',
        'headers' => [
            'Authorization' => 'Bearer {{secret:SHOP_API_TOKEN}}',
            'Accept' => 'application/json',
        ],
    ],
],

Der ToolRunner expandiert den Marker nur unmittelbar vor jedem HTTP-Call — nirgendwo sonst. Damit:

• bleibt die Config-Datei lesbar (Marker statt Konkat-Code),
• landen Secrets nie in Logs, Tool-Catalog, LLM-Kontext oder Knowledge-Index,
• ist Resolution-Stelle klar isoliert.

Für komplexere Handler-Logik (JWT-Signierung etc.) gibt es zusätzlich den secret($key)-Helper. Beide Pfade nutzen denselben Backing-Store, beide sind tenant-isoliert.

#Untracked Tenants (externe Devs, eigenes Workspace-Repo)

Speicherort:

Workflow:

tm pull           # Holt Configs + legt .env-Skeleton an falls noch nicht da
$EDITOR .env      # Echte Werte eintragen
tm sync           # Configs hoch — .env bleibt lokal

Wichtig:

• .env ist in .gitignore und wird nicht über tm pull / tm sync synchronisiert.
• Auf dem Server legst du sie einmalig ab (via SSH oder Onboarding-Befehl deines Betreibers).
• Bei Key-Rotation: in der .env ändern. Live-Wirkung beim nächsten Request, kein Deploy.

#Tracked Tenants (Workspace im selben Git-Repo wie TaskMonkey)

Gilt nur, wenn dein Tenant-Verzeichnis Teil des mecogpt-Repos ist (nicht der Standard für externe Devs).

Speicherort:

Begründung der Trennung: Das Tenant-Verzeichnis selbst liegt im Git — eine .env darin wäre schnell aus Versehen committed. Deshalb der Spiegel-Pfad tenants_untracked/<code>/ auf Repo-Root, der explizit ignoriert ist.

Workflow:

git pull
mkdir -p tenants_untracked/<code>
$EDITOR tenants_untracked/<code>/.env
# Server-Seite bleibt unverändert — nur lokal befüllen

#.env-Format

# Kommentare mit '#' am Zeilenanfang
KEY=value
QUOTED="value with spaces"
EMPTY=

Keine Variable-Expansion, keine Multi-Line-Strings. Ein Key pro Zeile.

#Welche Keys gibt es

config/tenants/_template/.env.example listet die Standard-Keys (Shopify, JTL, SendGrid, Anthropic, Meta, SMTP, Trello, FinAPI, Dropbox, TinyPNG) mit Kommentaren. tm pull legt auf Wunsch eine Kopie davon als Skeleton in deine .env an.

#Sicherheits-Checkliste

• .env ist nicht im Git-Working-Tree sichtbar (git status zeigt sie nicht).
• Keine Tokens als Klartext in apis.php oder Tool-Configs.
• Bei Workspace-Wechsel: alte .env löschen, neue für den neuen Tenant.
• Bei Token-Leak (Repo-Push aus Versehen, Mitarbeiter-Wechsel): Token rotieren beim Provider + .env aktualisieren.

#Was passiert wenn ich secret() nicht nutze

Klartext in apis.php funktioniert technisch weiter. Aber:

• Der Token wandert beim tm pull zwischen Server und Client hin und her,
• landet in Knowledge-Index, Tool-Listen und Backups,
• ist im Klartext bei jedem Mitarbeiter mit Repo-Zugriff sichtbar.

secret() ist daher der empfohlene Pfad für alle Neuanlagen und bei Migration alter Configs.