Skip to main content

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​

WerAufgabe
Besucher-App (v0)Route /k/[token], BFF ruft Cockpit-Restore auf, setzt Cookie loop_card, leitet auf /loop
CockpitRecovery-Hash in DB, Public-API session/restore, Felder bei Kartenanlage und Wallet
RedaktionvisitorAppBaseUrl im LOOP-Programm (Basis für recoveryUrl)

Wo​

ThemaOrt
Migrationpackages/database/migrations/20261011120000_loop_recovery_token_SAFE.sql
RestorePOST /api/public/loyalty/session/restore
Karte anlegenPOST /api/public/loyalty/cards → recoveryToken, recoveryUrl
Wallet Back-FeldPasscreator-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 bei POST /cards als httpOnly-Cookie loop_card speichern — 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:

FeldBedeutung
recoveryTokenEinmalig speichern (Wallet, E-Mail, Druck) — nur Hash in DB
recoveryUrlhttps://<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 ersten POST /wallet/pass ein neues Recovery-Token für den Pass-Link. Der Link aus der Kartenanlage (recoveryUrl in der Create-Antwort) ist danach ungültig — bevorzugt den Pass-Link nutzen.
  • Sync nach Stempel aktualisiert recoveryUrl nicht erneut (kein Klartext in DB).

Sicherheit​

  • Recovery- und Karten-Tokens ** nie** loggen; Referrer kann /k/<token> in Server-Logs tragen — v0 soll /k/* mit Referrer-Policy: no-referrer oder 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​

  1. Programm aktiv, visitorAppBaseUrl = https://<v0>/loop/stempel.
  2. POST /cards → recoveryToken, recoveryUrl notieren.
  3. POST /session/restore mit recoveryToken → 200, neues cardToken, GET /cards/me mit neuem Bearer funktioniert.
  4. Altes cardToken → 401.
  5. Falsches Recovery → 401 INVALID_RECOVERY.
  6. Optional: POST /wallet/pass → Pass-Feld recoveryUrl gesetzt.

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: /en/developer-guide/loop-session-reentry