Michael/breznflow
1
1
Fork 0
Code Issues Pull requests Projects Releases 5 Packages Wiki Activity Actions
breznflow/README.de.md
Michael 5c4d5f6686 release: v1.0.4 
Security

- Add looks_like_secret() entropy heuristic: vendor regex (AIza, sk-,
  ghp_, gho_, Slack xox, Bearer) + length/char-class fallback +
  path/whitespace denylist. Defensible hybrid: zero false-positives
  on known token formats, catches custom tokens without tripping on
  URLs or slugs.
- Gate generic 'key'-named fields and ?key= URL params with the
  entropy heuristic. Closes the n8n queryParameters Google-API-key
  bypass without false-positives on benign values.
- Entropy fallback in mask_name_value_pair for custom-header value
  patterns (X-App-Token etc.) whose names we cannot enumerate.
- Redact credentials[].name per node (id retained), clear
  meta.instanceId so exports no longer correlate to the source n8n
  instance.
- Opt-in tag clearing at publish time: wizard step 3 checkbox with
  the current tag list inline, only shown when tags exist.
- Wizard step 3 now renders a collapsible Reason / Key / Note table
  so publishers can verify exactly what was masked before publishing.

Mobile

- touch-action: none on .breznflow-svg to stop the
  browser-vs-plugin gesture tug-of-war.
- Rewrote pointer handling as a Map-based multi-pointer state
  machine with { passive: false } listeners: single-finger pan is
  now smooth on iOS and Android, pinch-to-zoom anchored at the
  finger midpoint, double-tap toggles 100/200 % zoom.
- Minimap ported to pointer events + setPointerCapture — tap and
  drag navigation work on touch.

Docs

- Expand Sensitive Data Masking section of both READMEs to describe
  the 1.0.4 passes and the opt-in tag removal.
- Version badge 1.0.3 -> 1.0.4.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-24 18:58:51 +00:00

366 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# BreznFlow
![PHP 8.0+](https://img.shields.io/badge/PHP-8.0%2B-blue)
![WordPress 6.0+](https://img.shields.io/badge/WordPress-6.0%2B-21759b)
![License: GPL-2.0](https://img.shields.io/badge/License-GPL--2.0--or--later-green)
![Version](https://img.shields.io/badge/Version-1.0.4-orange)
🇬🇧 [English version → README.md](README.md)
---
BreznFlow ist ein WordPress-Plugin, das n8n-Automations-Workflows als interaktive SVG-Diagramme rendert — direkt in Beiträgen und Seiten. Workflow-JSON einfügen, und das Plugin erzeugt ein zoombares, klickbares Diagramm mit Node-Detail-Panel, automatischer Maskierung sensibler Daten und farbcodierten Node-Icons.
Keine externen Abhängigkeiten. Kein CDN. Kein Tracking. Vanilla JavaScript. Ein Shortcode: `[breznflow id="X"]`.
---
## Warum dieses Plugin existiert
n8n-Workflows sind mächtig, aber visuell teilen ist überraschend schwierig. Screenshots sind statisch und veralten schnell. Den n8n-Editor einzubetten ist unpraktisch. JSON in einen Blogpost kopieren ist unlesbar.
BreznFlow löst das, indem es den rohen JSON-Export in ein interaktives Diagramm verwandelt — die gleichen Nodes, die gleichen Verbindungen, aber als sauberes SVG innerhalb von WordPress gerendert. Leser können zoomen, pannen und jeden Node anklicken, um seine Parameter zu sehen.
Entwickelt in Passau, Bayern — für [mifupa.com](https://mifupa.com), einem persönlichen Blog, auf dem regelmäßig n8n-Automationen vorgestellt werden und eine bessere Darstellung brauchten.
---
## Inhaltsverzeichnis
- [Warum dieses Plugin existiert](#warum-dieses-plugin-existiert)
- [Verzeichnisstruktur](#verzeichnisstruktur)
- [Features](#features)
- [Datenspeicherung](#datenspeicherung)
- [Sicherheit](#sicherheit)
- [Shortcode](#shortcode)
- [Installation](#installation)
- [Technischer Stack](#technischer-stack)
- [Lizenz](#lizenz)
---
## Verzeichnisstruktur
```
breznflow/
├── breznflow.php # Plugin-Header, Konstanten (BREZNFLOW_VERSION, BREZNFLOW_DIR, BREZNFLOW_URL)
├── uninstall.php # Aufräumen bei Plugin-Löschung
├── readme.txt # WordPress.org Plugin-Readme
├── assets/
│ ├── admin.css # Admin-Stylesheet (Wizard, Settings, Listtable)
│ ├── admin.js # Admin-JavaScript (Wizard-Schritte, JSON-Validierung)
│ ├── renderer.css # Frontend SVG-Renderer Styles
│ ├── renderer.js # Frontend-Renderer (SVG-Engine, Pan/Zoom, Detail-Panel)
│ ├── brezn.css # Legacy Brezn-Theme (Kompatibilität)
│ └── themes/
│ ├── dark.css # Dark-Theme (Standard)
│ ├── light.css # Light-Theme
│ ├── minimal.css # Minimal-Theme
│ ├── tech.css # Tech-Theme
│ └── brezn.css # Brezn-Theme
├── includes/
│ ├── Core.php # Singleton-Bootstrap, lädt alle Abhängigkeiten
│ ├── PostType.php # CPT breznflow_workflow + Taxonomie breznflow_category
│ ├── Shortcode.php # [breznflow] Shortcode mit 13 Attributen
│ ├── DownloadHandler.php # JSON-Download-Endpunkt (?breznflow_download={id})
│ ├── EmbedHandler.php # Standalone Embed-Seite (?breznflow_embed={id})
│ ├── Admin/
│ │ ├── AdminMenu.php # Menüstruktur + Dashboard-Render
│ │ ├── SettingsPage.php # Plugin-Einstellungen (16 Optionen, validiert)
│ │ ├── ThemesPage.php # Theme-Verwaltung (Import/Löschen eigener Themes)
│ │ ├── WizardPage.php # 3-Schritt Import-Wizard (Einfügen/Upload → Konfigurieren → Vorschau)
│ │ ├── WorkflowListTable.php # WP_List_Table für Workflow-Verwaltung
│ │ └── views/ # PHP-Templates für alle Admin-Seiten
│ ├── Features/
│ │ ├── NodeTypeRegistry.php # 86 Node-Typen mit Markenfarben und Icons
│ │ ├── NodeCategorizer.php # Kategorisiert Nodes (Trigger, Action, Logic, AI, etc.)
│ │ ├── InfoBoxBuilder.php # „3× HTTP Request, 2× Code" Node-Zusammenfassung
│ │ ├── ViewCounter.php # View-Zähler pro Workflow
│ │ ├── RelatedWorkflows.php # Ähnliche Workflows nach gemeinsamen Node-Typen
│ │ ├── ThemeRegistry.php # 5 Built-in-Themes + Custom-Theme-Support
│ │ └── ThemeImporter.php # Import/Export von .breznflow.json Theme-Dateien
│ └── Security/
│ ├── MaskingRules.php # Secret-Erkennung (URL-Parameter, Header, Entropie)
│ ├── WorkflowValidator.php # JSON-Schema-Validierung für n8n-Exporte
│ └── WorkflowSanitizer.php # Zwei-Pass-Sanitierung: Strings + Secret-Maskierung
└── languages/
├── breznflow.pot # Übersetzungsvorlage
├── breznflow-de_DE.po # Deutsche Übersetzung
└── breznflow-de_DE.mo # Kompilierte deutsche Übersetzung
```
---
## Features
### Interaktiver SVG-Renderer
Das Herzstück von BreznFlow. Jeder n8n-Node wird zu einem klickbaren SVG-Element mit farbcodierten Icons, Verbindungslinien und Labels. Der Renderer unterstützt:
- **Pan & Zoom** — Mausrad zoomt zur Cursorposition, Klick-Drag zum Verschieben
- **Node-Klick** — öffnet das Detail-Panel unterhalb des Diagramms mit allen Node-Parametern
- **Auto-Fit** — Workflows über einem konfigurierbaren Node-Schwellenwert (Standard: 30) zoomen automatisch zum Trigger-Node beim Laden
- **Minimap** — optionales Minimap-Overlay zur Navigation in großen Workflows
- **Vollbild** — Portal-basierter Vollbildmodus
Alles wird clientseitig in Vanilla JavaScript gerendert — kein Canvas, kein WebGL, keine externen Bibliotheken.
---
### 3-Schritt Import-Wizard
1. **Einfügen oder hochladen** — JSON direkt einfügen, `.json`-Datei hochladen oder von URL abrufen
2. **Konfigurieren** — Darstellungsmodus, Theme, Zoom, Titel, Kategorien einstellen
3. **Vorschau** — Live-SVG-Vorschau mit Maskierungs-Zusammenfassung vor dem Veröffentlichen
Der Wizard validiert JSON gegen das n8n-Schema, sanitiert alle Strings und maskiert erkannte Geheimnisse. Das Maskierungs-Protokoll zeigt genau, was entfernt wurde und warum.
**Import von URL:** Ruft Workflow-JSON von beliebigen öffentlichen URLs per `wp_remote_get()` ab. Anfragen an private/interne Netzwerkadressen (localhost, LAN-Bereiche, Cloud-Metadaten-Endpunkte) werden blockiert.
---
### Node Type Registry
86 vordefinierte Node-Typen mit markengetreuen Farben und 2-Buchstaben-Icons:
| Kategorie | Beispiele |
|---|---|
| Trigger | Schedule, Webhook, Manual, Form |
| Kernlogik | HTTP Request, Code, IF, Switch, Merge, Filter |
| Datentransformation | HTML, XML, Markdown, Crypto |
| Datenbanken | MySQL, PostgreSQL, Redis, MongoDB, SQLite, Supabase |
| Kommunikation | Slack, Telegram, Discord, Gmail, WhatsApp |
| Google | Sheets, Drive, Calendar, Docs, YouTube |
| Dev-Tools | GitHub, GitLab, Jira, Confluence, Linear, Notion |
| KI | OpenAI, Claude, Gemini, Ollama, Hugging Face, Mistral, LangChain |
| Speicher | FTP, SSH, Airtable, Baserow |
| CRM/Marketing | HubSpot, Salesforce, Mailchimp, Brevo |
Unbekannte Node-Typen bekommen einen deterministischen Fallback: 2-Buchstaben-Initialen und eine Farbe aus einem djb2-Hash — der gleiche unbekannte Typ sieht immer gleich aus.
---
### Theme-System
5 Built-in-Themes: **Dark** (Standard), **Light**, **Minimal**, **Tech**, **Brezn**.
Eigene Themes können als `.breznflow.json`-Dateien mit 41 CSS-Farbtokens importiert werden. Custom-Themes werden in `wp_options` gespeichert und als Inline-CSS-Variablen gerendert.
Themes sind global, pro Workflow oder pro Shortcode wählbar via `theme="dark"`.
---
### Action Bar
Unterhalb des Diagramms (nicht im Compact-Modus) bietet die Action Bar:
| Aktion | Steuerung | Funktion |
|---|---|---|
| **Share** | Globale Einstellung | Zeigt Artikel-Link + Anker-Link für Hash-Navigation |
| **Embed** | Global + pro Post | Zeigt iframe-Embed-Code für Standalone-Einbettung |
| **Get JSON** | Globale Einstellung | Zeigt formatiertes JSON mit Größe in KB |
| **Download** | Global + pro Post | Lädt sanitiertes JSON als Datei herunter |
Jede Aktion ist global in den Einstellungen steuerbar und per Shortcode überschreibbar.
---
### Maskierung sensibler Daten
BreznFlow speichert nie das rohe Workflow-JSON. Vor dem Speichern läuft eine Drei-Pass-Sanitierung:
**Pass 1 — String-Sanitierung:** Alle Strings durchlaufen `sanitize_text_field()`. Ausnahme: `jsCode`-Felder bleiben erhalten, werden aber mit `esc_html()` ausgegeben (nie ausgeführt).
**Pass 2 — Secret-Erkennung:**
- **URL-Parameter:** `api_key`, `token`, `secret`, `password`, `access_token`, `auth`, `client_secret` in Query-Strings → `[REDACTED]`
- **Generische `?key=`-URL-Parameter** *(1.0.4)*: werden nur redactet, wenn der gefangene Wert `looks_like_secret()` matcht — schließt die Google-API-Key-Lücke ohne False-Positives auf harmlosen Werten.
- **Header-Werte:** Authorization, Bearer, X-API-Key und ähnliche Header-Namen in `{name, value}`-Paaren → Wert maskiert
- **Wert-Entropie-Fallback** *(1.0.4)*: `{name, value}`-Paare, deren Name die Allowlist nicht matcht, werden dennoch maskiert, wenn der Wert selbst secret-förmig aussieht — deckt Custom-Header (`X-App-Token`) und n8ns generisches `queryParameters.key`-Pattern ab.
- **Bekannte Vendor-Token** *(1.0.4)*: `looks_like_secret()` matcht `AIza…`, `sk-…`, `ghp_…`, `gho_…`, Slack `xox…`, `Bearer …` (JWT) — plus Längen- und Zeichenklassen-Entropie-Fallback sowie Pfad-/Whitespace-Denylist gegen False-Positives.
- **Hochentropie-Bedingungen:** Werte in IF/Switch-Conditions, die UUID-Muster, Groß-/Kleinschreibung+Ziffern oder lange Strings ohne Leerzeichen matchen → per Entropie-Heuristik maskiert
- **Credential-Anzeigenamen** *(1.0.4)*: `credentials[].name` pro Node wird durch `[REDACTED]` ersetzt (die `id` bleibt — sie referenziert die n8n-DB und ist ohne den Server wertlos).
**Pass 3 — Identifizierende Metadaten** *(1.0.4)*: `meta.instanceId` wird geleert, damit Workflow-Exporte nicht mehr der ausgebenden n8n-Instanz zugeordnet werden können.
**Optional — Tag-Entfernung** *(1.0.4)*: Wizard Schritt 3 bietet eine Opt-in-Checkbox zum Entfernen von Workflow-Tags. Tags sind oft harmlos (`production`, `v2`), manchmal aber identifizierend — der Publisher entscheidet pro Workflow.
Ein **Maskierungs-Protokoll** zeichnet jedes maskierte Element mit Grund, Key und Hinweis auf. Schritt 3 zeigt es als ausklappbare Grund / Key / Hinweis-Tabelle, damit der Publisher vor Publish genau prüfen kann was veröffentlicht wird.
---
### Darstellungsmodi
| Modus | Was angezeigt wird |
|---|---|
| `visual` | Vollständiges Diagramm mit Toolbar, Detail-Panel, Action Bar |
| `info` | Nur Node-Zähler (InfoBox) — kein Diagramm |
| `compact` | Diagramm ohne Toolbar und Action Bar |
Konfigurierbar global, pro Workflow oder pro Shortcode.
---
### Embed-Handler
Liefert eine Standalone-HTML-Seite unter `?breznflow_embed={id}` für iframe-Einbettung. Die Seite enthält nur den SVG-Renderer — kein WordPress-Theme, keine Admin-Bar.
**Dual-Gate-Sicherheit:** Sowohl die globale `allow_embed`-Einstellung als auch das Per-Post-Meta `_breznflow_show_embed` müssen aktiviert sein.
URL-Parameter: `?theme={id}` und `?minimap=0|1`.
HTTP-Header enthalten `X-Robots-Tag: noindex, nofollow` und entfernen `X-Frame-Options` für Embedding.
---
### Weitere Features
- **View-Zähler** — zählt, wie oft jeder Workflow angezeigt wird
- **Ähnliche Workflows** — zeigt verwandte Workflows nach gemeinsamen Node-Typen
- **InfoBox** — kompakte Zusammenfassung wie „3× HTTP Request, 2× Code, 1× OpenAI"
- **KI-Erkennung** — erkennt und markiert automatisch Workflows mit KI-Nodes
- **Schema.org HowTo** — optionale JSON-LD-Strukturdatenausgabe
- **Anker-Navigation** — `<span id="breznflow-{id}">` für Hash-basiertes Deep-Linking mit 60px Scroll-Offset
---
## Datenspeicherung
### WordPress Options (wp_options)
| Option-Key | Inhalt |
|---|---|
| `breznflow_settings` | Alle Plugin-Einstellungen (16 Keys, serialisiertes Array) |
| `breznflow_custom_themes` | Custom-Theme-Definitionen (serialisiertes Array) |
### Post Meta (wp_postmeta)
| Meta-Key | Inhalt |
|---|---|
| `_breznflow_raw_json` | Sanitiertes Workflow-JSON (nie das Roh-Original) |
| `_breznflow_original_name` | Originaler Workflow-Name aus n8n |
| `_breznflow_node_count` | Gesamtzahl der Nodes |
| `_breznflow_node_summary` | Kategorisierte Node-Anzahl (JSON) |
| `_breznflow_has_ai_nodes` | Ob der Workflow KI-Nodes enthält |
| `_breznflow_ai_node_types` | Liste der KI-Node-Typen (JSON) |
| `_breznflow_mask_log` | Maskierte Werte beim Import (JSON) |
| `_breznflow_default_zoom` | Zoom-Level pro Workflow (10–200) |
| `_breznflow_show_title` | Titel anzeigen |
| `_breznflow_show_infobox` | InfoBox anzeigen |
| `_breznflow_show_download` | Download erlauben |
| `_breznflow_show_embed` | Einbettung erlauben |
| `_breznflow_show_minimap` | Minimap anzeigen |
| `_breznflow_default_mode` | Darstellungsmodus |
| `_breznflow_default_theme` | Theme-ID |
### Uninstall-Cleanup
`uninstall.php` löscht bei Plugin-Deinstallation:
- Alle `breznflow_workflow`-Posts und deren Meta
- Option `breznflow_settings`
- Alle `breznflow_category`-Taxonomie-Terms
- Alle Transients mit Präfix `breznflow_`
---
## Sicherheit
### Eingabevalidierung
- Workflow-JSON wird vor dem Import gegen das n8n-Schema validiert
- Alle `$_POST` / `$_GET`-Werte über `wp_unslash()` + spezifische Sanitizer verarbeitet
- Alle Ausgaben escaped mit `esc_html`, `esc_attr`, `esc_url`
- SQL-Queries ausschließlich via `$wpdb->prepare()`
### CSRF-Schutz
Jede Admin-Aktion validiert eine WordPress-Nonce. Capability-Checks erfordern `manage_options` für Einstellungen und `edit_posts` für Workflow-Verwaltung.
### Download- & Embed-Sicherheit
Beide Endpunkte validieren:
1. Post existiert, ist Typ `breznflow_workflow` und Status `publish`
2. Die entsprechende Per-Post-Meta-Berechtigung ist aktiviert
3. Die globale Einstellung ist aktiviert
4. Das gespeicherte JSON ist valide
Response-Header enthalten `X-Content-Type-Options: nosniff`. Downloads nutzen `Cache-Control: no-store`.
### Import von URL
Das „Von URL abrufen"-Feature im Wizard blockiert Anfragen an private/interne Netzwerkadressen (localhost, `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, Cloud-Metadaten-Endpunkte) zur Verhinderung von SSRF-Angriffen.
---
## Shortcode
```
[breznflow id="42"]
[breznflow id="42" mode="compact" theme="light" zoom="80"]
[breznflow id="42" show_share="0" show_embed="1" show_minimap="0"]
```
| Attribut | Standard | Beschreibung |
|---|---|---|
| `id` | — | Workflow-Post-ID (erforderlich) |
| `mode` | `visual` | `visual`, `info` oder `compact` |
| `theme` | `dark` | Theme-ID |
| `zoom` | `100` | Initiales Zoom-Level (10–200) |
| `show_title` | `true` | Workflow-Titel anzeigen |
| `show_infobox` | `true` | Node-Zusammenfassung anzeigen |
| `show_minimap` | `true` | Minimap-Overlay anzeigen |
| `show_download` | `false` | Download-Button anzeigen |
| `show_share` | `true` | Share-Aktion anzeigen |
| `show_embed` | `false` | Embed-Aktion anzeigen |
| `show_get_json` | `false` | „Get JSON"-Aktion anzeigen |
| `max_code_lines` | `50` | Max. Zeilen in Code-Node-Anzeige |
**Auflösungs-Hierarchie:** Shortcode-Attribut → Post-Meta → Plugin-Einstellungen.
---
## Installation
**Via GitHub Release (empfohlen):**
1. `breznflow.zip` vom [neuesten Release](https://github.com/noschmarrn/breznflow/releases/latest) herunterladen
2. In WordPress unter *Plugins → Installieren → Plugin hochladen* einspielen
**Manuell (clone):**
```bash
cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/noschmarrn/breznflow.git
wp plugin activate breznflow
```
**Nach der Aktivierung:**
1. *BreznFlow → Workflow hinzufügen*
2. n8n Workflow-JSON einfügen (oder `.json`-Datei hochladen)
3. Darstellungseinstellungen konfigurieren und Vorschau prüfen
4. Veröffentlichen — `[breznflow id="X"]` in beliebigen Beitrag oder Seite einfügen
Kein Build-Step. Alle Assets sind direkte JS/CSS-Dateien.
---
## Technischer Stack
| Komponente | Technologie |
|---|---|
| Backend | PHP 8.0+, WordPress Plugin API |
| Namespace | `BreznFlow\` |
| Architektur | Singleton-Core, Feature-Klassen mit `register()` |
| Rendering | Vanilla JavaScript SVG-Generierung (kein Canvas, keine Bibliotheken) |
| Datenbank | WordPress Options API + Post Meta |
| Caching | WordPress Transients (Related Workflows) |
| Frontend | Vanilla JS, kein Build-Step, kein externes CDN |
| I18n | `.pot`-File, Text-Domain `breznflow` |
| Coding Standard | WordPress PHPCS |
| Lizenz | GPL-2.0-or-later |
---
## Lizenz
GPL-2.0-or-later — [https://www.gnu.org/licenses/gpl-2.0.html](https://www.gnu.org/licenses/gpl-2.0.html)
Copyright (c) 2025–2026 [mifupa.com](https://mifupa.com)
Reference in a new issue View git blame Copy permalink