rebreak-monorepo/docs/concepts/brand-token-matching.md

# Konzept: Geteiltes Brand-Token-Matching

Status: **Konzept abgenommen (2026-05-22) — im Backlog, Umsetzung später (§10)**
Datum: 2026-05-22
Scope: Layer 1 (DNS-Sinkhole / PacketTunnel) + Mail-Scan (Mo). NICHT Layer 2.

---

## 1. Problem

Glücksspiel-Marken umgehen exakte Blocklisten mit dem **Nummern-/Suffix-Trick**:
dieselbe wiedererkennbare Marke, variierende Zahl/Suffix/TLD.

```
slotoro.bet  →  slotoro88.bet · slotoro2.com · slotoro-casino.net · slotorobet.io
winrolla.com →  winrolla57.com · winrolla-bet.net
```

- **Layer 1** (DNS-Hash-Set, 329k Hashes): matcht nur **exakt**. Hashes erlauben
  kein Substring-/Prefix-Matching — `slotoro88.bet` hasht zu etwas völlig anderem
  als `slotoro.bet`. Architektur-bedingt.
- **Layer 2** (Apple `ManagedSettings`-`WebDomain`): matcht nur exakte Domain +
  Subdomains. Keine Substring-API. **Nicht erweiterbar** — out of scope.
- **Mail-Scan (Mo)**: hat dasselbe Problem (`winrolla → winrolla57`).

Die HaGeZi-Feed-Liste fängt viele Varianten mit **Latenz** — der Feed muss die
neue Variante erst aufnehmen. Brand-Token-Matching schließt genau diese
Latenzlücke und greift sofort bei jeder Variante einer **bekannten** Marke.

---

## 2. Ziel & Scope

**Ziel:** Ein einziges, geteiltes Brand-Token-System — dieselbe kuratierte
Token-Liste + derselbe Matching-Algorithmus für Layer 1 (DNS) und Mail-Scan.

**Im Scope:** Varianten **bekannter** Marken abfangen.
**Nicht im Scope:**
- Brandneue Marken ohne Token (kein Token → kein Match).
- Layer 2 (Apple-API kann es nicht).
- Ersatz für Feed/Blocklist — das System **ergänzt** sie, ersetzt sie nicht.

---

## 3. Kernidee: der Brand-Token

Ein **Brand-Token** = ein distinktiver, kleingeschriebener Marken-Kern, der eine
Glücksspielmarke identifiziert und in legitimen Domains praktisch nicht vorkommt.

```
Gute Tokens:    slotoro · winrolla · spinrollz · wazamba
Schlechte Tokens: bet · win · play · casino · slot · vegas
                  (Wörterbuch-/Generikwörter → False-Positive-Magneten)
```

Regel: **kuratiert, nie automatisch.** Mindestlänge **≥ 5 Zeichen**. Kürzere
Marken bleiben bei der exakten Blocklist.

---

## 4. Der Matching-Algorithmus (das geteilte Stück)

Der entscheidende Teil. **Kein freies Substring** (`host.contains(token)` ist
gefährlich). Stattdessen **Entnummerierung + Segment-Exaktvergleich**:

### Ablauf (pro Host)

```
1. Host in Labels splitten an '.'        slotoro88.bet → ["slotoro88", "bet"]
2. Pro Label: in Segmente splitten an '-'  play-slotoro → ["play", "slotoro"]
3. Pro Segment:
   a. Trailing-Ziffernlauf abschneiden → `core`   slotoro88 → slotoro
   b. core EXAKT in tokenSet?                     → MATCH
   c. sonst: core beginnt mit einem Token UND
      der Rest ∈ genericSuffixSet?                → MATCH
   d. sonst                                       → kein Match
4. Kein Segment matcht → kein Block.
```

`genericSuffixSet` = generische Glücksspiel-Anhängsel, die nur als **Rest nach
einem Token** zählen (nie standalone): `bet bets casino casinos slot slots spin
spins win wins play vegas game games poker sport sports wetten lotto gambling`.

### Warum das robust ist

Es ist **Exaktvergleich auf dem entnummerierten Segment**, kein Substring.
Ein kurzes Token wie `win` würde `winter` NICHT treffen: `winter` → core
`winter` → `winter` ≠ `win` → kein Match. False Positives entstehen nur, wenn
ein legitimes Segment **exakt** ein Token ist — bei distinktiven Tokens ~null.

### Beispiele

| Host | Segment-core | Ergebnis |
|---|---|---|
| `slotoro.bet` | `slotoro` | MATCH (exakt) |
| `slotoro88.bet` | `slotoro88`→`slotoro` | MATCH (entnummeriert) |
| `slotoro2.com` | `slotoro2`→`slotoro` | MATCH |
| `play-slotoro.net` | Segment `slotoro` | MATCH |
| `slotoro-casino.io` | Segment `slotoro` | MATCH |
| `slotorobet.com` | `slotorobet` = `slotoro`+`bet` | MATCH (Token+Suffix) |
| `stat.slotoro88.bet` | Label `slotoro88`→`slotoro` | MATCH |
| `winter.com` | `winter` | kein Match (≠ Token) |
| `slotorox.com` | `slotorox` = `slotoro`+`x`, `x`∉Suffixe | kein Match |

### Verbindlichkeit

Der Algorithmus muss **bit-identisch** in Swift (PacketTunnel) und TS
(Mo-Scan + Backend-Validierung) implementiert sein — analog zu
`domainHash.ts` ↔ `DomainHasher.swift`. Ein gemeinsamer Spec-Testvektor-Satz
(Input-Host → erwartetes Ergebnis) wird in beiden Test-Suites geprüft.

---

## 5. Token-Liste: Kuration & Quelle

- **DB-Tabelle** `brand_tokens` (token, source, addedAt, isActive, note).
- **Kuratiert von ReBreak-Admins** — nie auto-generiert (FP-Risiko).
- **Bootstrap:** die existierende 329k-Blocklist nach gemeinsamen SLD-Präfix-
  Clustern minen → Token-Vorschläge → menschliche Freigabe.
- **Laufende Quelle:** wenn ein User über die Custom-Domain-/Submission-Flows
  eine offensichtliche Variante einreicht, kann der Admin statt nur der Domain
  das **Brand-Token** promoten.
- **Allowlist-Notausgang** (`brand_token_allowlist`): falls ein Token doch
  kollidiert, einzelne legitime Domains explizit ausnehmen. v1 optional, im
  Design vorgesehen.

---

## 6. Verteilung aufs Gerät (Layer 1)

- Neuer Endpoint `GET /api/url-filter/brand-tokens` — JSON/Zeilenliste, ETag-
  gecacht. Spiegelt exakt den `blocklist.bin`-Sync-Mechanismus:
  App lädt → schreibt in App-Group → Darwin-Notification → Extension reloadet.
- Datei klein (~wenige KB bei einigen hundert Tokens).
- **File-Protection `.completeUntilFirstUserAuthentication`** — wie nach dem
  Layer-1-Bugfix (2026-05-22), damit die Extension sie auch bei gesperrtem
  Gerät lesen kann.
- **Privacy-Abwägung (ehrlich):** die Hash-Liste ist gehasht, damit keine
  Klartext-Casino-Domains auf dem Gerät eines Spielers liegen. Brand-Tokens
  sind Klartext-Markenfragmente — Substring-Matching gegen Hashes ist
  unmöglich, Klartext ist also nötig. Es sind aber nur einige hundert
  Markenfragmente, kein browsing-history-verräterischer Datensatz. Datei
  file-protected. **Entscheidung (2026-05-22): Klartext akzeptiert.**
  `hans-mueller`-DSGVO-Gegencheck bei der Umsetzung (kein Blocker fürs Konzept).

---

## 7. Integration

### Layer 1 — `DnsFilter.classify`
Nach dem `hashList.matchesAnySuffix(domain)`-**Miss**, vor `.forward`:

```
if hashList-Miss:
    if brandTokens.matches(domain):   // der Algo aus §4
        return .block
return .forward
```

Neue Klasse `BrandTokenList` (Pendant zu `HashList`) — lädt die Token-Datei,
reloadet via Darwin-Notification. Performance: pro verfehlter Query ein paar
Set-Lookups → Mikrosekunden, NE-Memory-unkritisch.

### Mail (Mo)
Derselbe `brandTokens.matches(...)` auf die Absender-Domain (und optional den
Display-Namen) anwenden. Owner der Integration bleibt Mo; das geteilte Stück
ist die Token-Liste + der §4-Algorithmus.

---

## 8. Was es NICHT tut (ehrliche Grenzen)

- Keine **neuen** Marken (ohne Token kein Match).
- Glued-Varianten ohne Ziffern/Trenner/Generik-Suffix (`slotoroxyz.com`) →
  Miss; bleibt Sache des Feeds.
- Kein Layer-2-Support.
- False Positives werden stark reduziert, nicht zu 100% eliminiert → Allowlist.

---

## 9. Entscheidungen

**Entschieden (2026-05-22):**
1. **Privacy:** Klartext-Brand-Tokens auf dem Gerät akzeptiert, file-protected.
   `hans-mueller`-DSGVO-Gegencheck bei der Umsetzung (kein Blocker fürs Konzept).
2. **Generic-Suffix-Regel (§4c):** drin — v1 enthält Token+Suffix-Matching
   (`slotorobet` = `slotoro`+`bet`).

**Noch offen (bei Umsetzung klären):**
3. **Token-Kuration:** rein Admin, oder community-/submission-gespeist?
4. **Sync-Kanal:** eigener Endpoint, oder in den `blocklist.bin`-Sync bündeln?
5. **Bootstrap-Aufwand:** Mining der 329k-Liste nach Präfix-Clustern — wie viel
   manuelle Freigabe ist realistisch?

---

## 10. Rollout-Phasen

- **Phase 1:** DB-Tabelle + §4-Algo-Spec + Testvektoren + Bootstrap-Mining +
  Admin-Kuration-UI.
- **Phase 2:** Endpoint + Sync + `BrandTokenList` + `DnsFilter`-Einbau (Layer 1).
- **Phase 3:** Mo-Mail-Integration.
- Hinter Feature-Flag, mit FP-Report-Pfad zum Monitoring.