LOOP — Stateless Session Reentry
Was
Besucher können ihre LOOP-Karte ohne gespeichertes Karten-Token wieder öffnen — z. B. über einen Link im Wallet-Pass oder einen QR-Code. Das Cockpit speichert nur einen Hash des Recovery-Tokens; der Klartext erscheint einmal bei Kartenanlage, optional bei Rotation oder beim ersten Wallet-Pass (siehe unten).
Warum
Geräte wechseln, Browser-Daten gehen verloren, Wallet-Pässe bleiben. Reentry stellt die Session (Karten-Token) wieder her, ohne personenbezogene Konten.
Wer
| Wer | Aufgabe |
|---|---|
| Besucher-App (v0) | Route /k/[token], BFF ruft Cockpit-Restore auf, setzt Cookie loop_card, leitet auf /loop |
| Cockpit | Recovery-Hash in DB, Public-API session/restore, Felder bei Kartenanlage und Wallet |
| Redaktion | visitorAppBaseUrl im LOOP-Programm (Basis für recoveryUrl) |
Wo
| Thema | Ort |
|---|---|
| Migration | packages/database/migrations/20261011120000_loop_recovery_token_SAFE.sql |
| Restore | POST /api/public/loyalty/session/restore |
| Karte anlegen | POST /api/public/loyalty/cards → recoveryToken, recoveryUrl |
| Wallet Back-Feld | Passcreator-Feld recoveryUrl (optional im Master-Template) |
Ablauf
Wichtig: Stempeln und Einlösen laufen weiter nur mit gültigem Karten-Token (Authorization: Bearer oder Cookie
über BFF). session/restore stellt nur die Session her.
API (v0-BFF)
POST /api/public/loyalty/session/restore
Body:
{ "recoveryToken": "<Klartext aus Link /k/…>" }
Erfolg 200:
{
"success": true,
"data": {
"cardToken": "…",
"card": { "cardNumber": "LP-…", "pointsBalance": 0, "stampCards": [] }
}
}
cardToken: Neues Session-Token (altes Bearer-Token der Karte ist danach ungültig). Im v0-BFF wie beiPOST /cardsals httpOnly-Cookieloop_cardspeichern — nicht im Client-JS ausgeben.- Antwort kann zusätzlich
Set-Cookie: loop_card=…tragen (Cockpit-Domain); für v0 zählt das BFF-Cookie.
Fehler: 401 INVALID_RECOVERY (generische Meldung, kein Token-Leak). Rate-Limit pro IP (15 min / 30 Versuche).
POST /api/public/loyalty/cards (Erweiterung)
Zusätzlich zu cardToken und card:
| Feld | Bedeutung |
|---|---|
recoveryToken | Einmalig speichern (Wallet, E-Mail, Druck) — nur Hash in DB |
recoveryUrl | https://<Origin der visitorAppBaseUrl>/k/<recoveryToken> wenn Programm-URL gesetzt, sonst null |
Wallet-Pass
- Dynamisches Feld
recoveryUrl(Back-Feld im Passcreator-Template empfohlen). - Erster Pass für eine Karte: Wenn bereits ein Recovery-Hash existiert (nach
POST /cards), aber kein Klartext mehr verfügbar ist, erzeugt das Cockpit beim erstenPOST /wallet/passein neues Recovery-Token für den Pass-Link. Der Link aus der Kartenanlage (recoveryUrlin der Create-Antwort) ist danach ungültig — bevorzugt den Pass-Link nutzen. - Sync nach Stempel aktualisiert
recoveryUrlnicht erneut (kein Klartext in DB).
Sicherheit
- Recovery- und Karten-Tokens ** nie** loggen; Referrer kann
/k/<token>in Server-Logs tragen — v0 soll/k/*mitReferrer-Policy: no-referreroder Redirect ohne Token in der Ziel-URL absichern (v0-Integration). - Rate-Limit auf Restore; Hash-Vergleich konstantzeitig nach DB-Lookup.
- Restore ersetzt das Karten-Session-Token (Rotation) — gestohlenes altes Bearer-Token wird ungültig.
So testen
- Programm aktiv,
visitorAppBaseUrl=https://<v0>/loop/stempel. POST /cards→recoveryToken,recoveryUrlnotieren.POST /session/restoremitrecoveryToken→200, neuescardToken,GET /cards/memit neuem Bearer funktioniert.- Altes
cardToken→401. - Falsches Recovery →
401 INVALID_RECOVERY. - Optional:
POST /wallet/pass→ Pass-FeldrecoveryUrlgesetzt.
Betrieb
Migration auf Render/Prod ausrollen, bevor Restore genutzt wird: 20261011120000_loop_recovery_token_SAFE.sql.
Siehe auch: LOOP Loyalty — API-Vertrag, v0-Integrationsvertrag.
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/loop-session-reentry