Quickstart

Quickstart: Live-Demo, Go-Lib & Terminal

Um die Hansestack API in deine Applikation einzubauen, musst du das k-Anonymity-Verfahren verstehen. Du sendest niemals das Passwort und niemals den kompletten Hash über das Netzwerk.

Wir bieten dir mehrere Wege, um das Konzept sofort zu testen und in deine Systeme zu integrieren.

1. Die Live-Demo - Sofort im Browser testen

Der schnellste Weg, die Architektur zu verstehen: Ohne Installation, ohne Setup, direkt in deinem Browser.

👉 Öffne die Live-Demo unter demo.hansestack.de

Die Demo zeigt dir ein Split-Screen-Setup: Links ein realistisches Login-Formular, rechts ein live mitlaufendes Grafana-Dashboard – genau die Observability, die auch unser Caddy-Plugin in Produktion liefert.

Der "Aha"-Moment: Logge dich mit dem absichtlich kompromittierten Passwort password123 ein. Beobachte, wie die Kachel "Confirmed ATOs" (Account Takeovers) im Dashboard in Echtzeit auf Rot springt – während der Login selbst dank Fail-Open-Architektur trotzdem ganz normal durchläuft. So sieht Decoupled Security in der Praxis aus.

Lokal nachbauen mit Docker Compose

Wenn du dir die Architektur genauer ansehen, den Traffic mitschneiden oder das Setup als Grundlage für eigene Tests nutzen willst, kannst du exakt dieselbe Umgebung lokal per Docker Compose starten.

API-Key holen: Registriere dich kostenlos im Portal und generiere einen API-Key.

Repository klonen:

git clone https://github.com/hansestack/leakcheck-caddy-demo.git
cd leakcheck-caddy-demo

Konfigurieren & Starten: Kopiere die .env.example zu .env, trage deinen API-Key ein und starte die Umgebung:
```
docker compose up
```

Damit läuft bei dir lokal derselbe Stack, den du unter demo.hansestack.de live ausprobiert hast: Caddy mit unserem Plugin, ein Beispiel-Backend und das Grafana-Dashboard. Du kannst nun Traffic-Analysen (Wireshark/Proxy) durchführen und live sehen, dass nur 5-Zeichen-Hashes dein lokales System verlassen.

Kein Caddy im Einsatz?

Die Demo zeigt unsere empfohlene Zero-Code-Integration via Caddy-Plugin (siehe Abschnitt 4). Für individuelle Backends bieten wir zusätzlich die Go-Library und rohe API-Zugriffe per Bash/cURL – siehe unten.

2. Integrationsoption für individuelle Backends: Die offizielle Go-Library (hansestack-go)

Setzt dein Backend nicht auf Caddy, sondern nutzt du Go direkt? Unsere offizielle Library übernimmt das Hashing, das Parsen der JSON-Antworten und vor allem das Fail-Open-Handling komplett für dich.

go get github.com/hansestack/hansestack-go

Minimales Beispiel:

package main

import (
	"context"
	"fmt"
	"time"
	"github.com/hansestack/hansestack-go/leakcheck"
)

func main() {
	// Initialisiert den Client mit einem strikten 500ms Fail-Open Timeout
	client := leakcheck.NewClient(
		"DEIN_API_KEY",
		leakcheck.WithTimeout(500*time.Millisecond),
	)

	leaked, count, err := client.CheckPassword(context.Background(), "Passwort123!")
	if err != nil {
		// FAIL-OPEN: Logge den Fehler, aber blockiere den Nutzer nicht!
		// Da wir standardmäßig Fail-Open nutzen, ist err in der Regel nil,
		// Netzwerkfehler werden intern geloggt. 
		fmt.Printf("API-Fehler (Login wird fortgesetzt): %v\n", err)
	}

	if leaked {
		fmt.Printf("Achtung: Passwort wurde %d mal in bekannten Leaks gefunden.\n", count)
	} else {
		fmt.Println("Sicher: Kein Leak gefunden. Login erfolgreich.")
	}
}

Weitere Details und den Quellcode findest du auf GitHub.

🤖 Agent Experience (AX) Ready

Nutzt du Cursor, Windsurf oder Copilot? Das Go-Repository enthält eine llms.txt. Die KI weiß dadurch automatisch, wie sie die Library Fail-Open-konform in deine Routen einbaut.

3. Integrationsoption für individuelle Backends: Under the hood mit Bash & cURL

Wenn du den rohen API-Flow (Hashen, Splitten, Abfragen) manuell nachbauen möchtest (z.B. für eigene Clients in Python oder Node.js), kannst du unser Bash-Skript als Referenz nutzen.

Für das Filtern der JSON-Antwort nutzen wir das Tool jq.

#!/bin/bash

API_KEY="DEIN_API_KEY_HIER"
API_URL="https://api.hansestack.de/leakcheck/v1/prefixes"

echo "Bitte Passwort eingeben:"
read -s PASSWORD

HASH=$(echo -n "$PASSWORD" | sha1sum | awk '{print $1}' | tr 'a-z' 'A-Z')
PREFIX=${HASH:0:5}
SUFFIX=${HASH:5}

RESPONSE=$(curl -s -w "\n%{http_code}" -H "X-API-Key: $API_KEY" -H "Accept: application/json" "$API_URL/$PREFIX")
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$HTTP_CODE" -ne 200 ]; then
    echo "API Fehler! HTTP Code: $HTTP_CODE"
    exit 1
fi

MATCH=$(echo "$BODY" | jq -r ".suffixes[\"$SUFFIX\"]")

if [ "$MATCH" != "null" ]; then
    echo "⚠️ WARNUNG: Dieses Passwort wurde $MATCH mal gefunden!"
else
    echo "✅ SICHER: Das Passwort ist in keiner Leak-Datenbank aufgetaucht."
fi

4. Caddy Reverse Proxy (Zero-Code) - Unsere Empfehlung

Die eleganteste Lösung für bestehende Systeme, und genau das, was du gerade in der Live-Demo gesehen hast: Unser natives Plugin für den Caddy Webserver. Es prüft Passwörter asynchron direkt auf Infrastruktur-Ebene, ohne dass du auch nur eine einzige Zeile Code in deinem Backend anfassen musst.

Für die meisten Teams ist dies der schnellste Weg zu produktivem Leak-Checking – kein SDK, kein Redeploy deines Backends, nur eine Zeile im Caddyfile.

Zur Caddy Plugin Dokumentation →

Caddy Plugin