# Zugriffsstufen

> Welche Passdaten öffentlich sind, welche eingeschränkt, und wie BatteryPass eingeschränkte Daten aus öffentlichen Antworten heraushält.

Die Batterieverordnung teilt die Daten eines Passes nach Empfängern auf (Art. 77 Abs. 2, Anhang XIII).
BatteryPass ordnet jedem Feld des Registers genau eine Zugriffsstufe zu und filtert serverseitig: Eine Antwort
enthält nie Daten oberhalb der Stufe, für die sie bestimmt ist.

## Die Stufen

`Tier` bezeichnet die Stufe eines Felds oder Dokuments, `PassportTier` die Stufe, auf die ein Passdokument
projiziert wird. Eine Projektion enthält ihre Stufe und die vorherigen: `legitimate_interest` schließt
`public` ein, `authority` beide.

| Stufe                 | Empfänger                                                                                                    | Beispiele                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `public`              | Alle, die den QR-Code scannen                                                                                | Hersteller, Kategorie, Chemie, Kapazität, Spannungen, gefährliche Stoffe, Konformitätserklärung                          |
| `legitimate_interest` | Personen mit berechtigtem Interesse sowie notifizierte Stellen, Marktüberwachungsbehörden und die Kommission | Detaillierte Zusammensetzung, Demontageinformationen, Batteriestatus, Zustandsdaten wie Kapazitätsverlust und Zyklenzahl |
| `authority`           | Notifizierte Stellen, Marktüberwachungsbehörden und die Kommission                                           | Ergebnisse von Prüfberichten                                                                                             |
| `internal`            | Nur Ihre Organisation                                                                                        | Nie Teil einer Passprojektion                                                                                            |

Die Stufe jedes Felds legt das Register fest: [`getRegistrySchema`](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-schema)
liefert `tier` für jedes Feld. Im aktuellen Register sind alle Felder der Zustandsdaten `legitimate_interest`.

## Die öffentliche Projektion

Bei der Veröffentlichung projiziert BatteryPass den Snapshot der Version auf die Stufe `public`, speichert das
Ergebnis als öffentliches Dokument der Version und [signiert es](https://passport.kabin.sh/docs/de/concepts/signatures). Öffentliche
Operationen liefern dieses gespeicherte Dokument; sie projizieren alte Versionen nie neu mit neuerem Code oder
einem neueren Register. Eine spätere Registeränderung kann in einer bereits veröffentlichten Version also weder
Daten offenlegen noch verbergen.

Das öffentliche Dokument enthält nur Felder der Stufe `public`. Für Felder darüber, die einen Wert haben,
nennt es in `restricted_fields_present` die Schlüssel, nie die Werte. Dokumente einer eingeschränkten Stufe
fehlen ganz, nicht einmal ihr Titel erscheint.

```bash title="cURL"
curl -s "$BATTERYPASS_URL/api/v1/public/passports/$PASSPORT_UUID" \
  | jq '{tier: .document.tier, restricted: .document.restricted_fields_present}'
```

```json title="Antwort"
{
  "tier": "public",
  "restricted": ["identification.battery_status", "condition.capacity_fade"]
}
```

## Öffentliche Operationen liefern nur die öffentliche Stufe

Diese Operationen brauchen keinen Schlüssel und liefern ausschließlich Daten der Stufe `public`:

| Operation                                                                                                                      | Liefert                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| [`getPublicPassport`](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport)                            | Das öffentliche Dokument der aktuellen Version                                           |
| [`getPublicPassportByProductId`](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport-by-product-id)   | Dasselbe, gesucht über GTIN und Seriennummer                                             |
| [`getPublicPassportVersion`](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport-version)             | Das öffentliche Dokument, das zu einem Zeitpunkt galt                                    |
| [`downloadPublicPassportDocument`](https://passport.kabin.sh/docs/de/api-reference/public/download-public-passport-document) | Ein Dokument der Stufe `public`, das ein öffentliches Feld nennt; alles andere ist `404` |
| [`verifyPassport`](https://passport.kabin.sh/docs/de/api-reference/public/verify-passport)                                   | Das Ergebnis der Signaturprüfung, ohne Daten                                             |

Der [Resolver](https://passport.kabin.sh/docs/de/concepts/digital-link) hinter dem QR-Code verweist auf dieselbe öffentliche Seite und
dasselbe JSON.

## Was ein API-Schlüssel liest

Ein API-Schlüssel liest die Pässe Ihrer eigenen Organisation mit den Rechten eines Betrachters, und dazu gehören
die eingeschränkten Stufen Ihrer eigenen Daten: Der `snapshot` von
[`getPassportVersion`](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport-version),
[`exportPassportJson`](https://passport.kabin.sh/docs/de/api-reference/passports/export-passport-json) und
[`exportPassportPdf`](https://passport.kabin.sh/docs/de/api-reference/passports/export-passport-pdf) enthalten alle Stufen. Eine Ausnahme:
Dateien der Stufen `authority` und `internal` dürfen nur Bearbeiter und höhere Rollen herunterladen, deshalb
antwortet [`downloadEvidence`](https://passport.kabin.sh/docs/de/api-reference/evidence/download-evidence) einem Schlüssel bei ihnen mit
`403 forbidden`.

> [!WARNING]
> Was Ihre Integration mit einem Schlüssel liest, ist nicht automatisch öffentlich. Halten Sie eingeschränkte Werte
> aus allem heraus, was Endkunden sehen, und veröffentlichen Sie nur, was das öffentliche JSON enthält.

## Eingeschränkte Stufen für Dritte

Dritte, etwa eine Werkstatt oder eine Behörde, lesen eingeschränkte Stufen nicht über die API. Dafür hat
BatteryPass einen eigenen Zugang im Portal:

- Er ist ausgeschaltet, solange der Betreiber der Installation ihn nicht einschaltet (`TIER_PORTAL_ENABLED`,
  standardmäßig aus). Solange er aus ist, enthält das öffentliche JSON kein `links.restricted`, und nichts
  verweist auf ihn.
- Ist er an, gibt ein Inhaber oder Admin des Wirtschaftsakteurs der E-Mail-Adresse eines Lesers die Stufe
  `legitimate_interest` oder `authority` frei, mit einem Zweck und einer Laufzeit von höchstens einem Jahr, und
  kann die Freigabe jederzeit widerrufen.
- Der Leser meldet sich mit dieser bestätigten Adresse im Portal an und sieht die aktuelle Version in der
  freigegebenen Stufe. Eingeschränkte Dokumente erscheinen nur mit ihrem Titel.
- Jeder eingeschränkte Lesezugriff wird im Audit-Log der Organisation des Passes festgehalten.

Dieser Zugang ist keine Funktion von API-Schlüsseln und nicht Teil des veröffentlichten Vertrags.

> [!NOTE]
> Der Durchführungsrechtsakt nach Art. 77 Abs. 9, der festlegt, wer ein berechtigtes Interesse hat und wie er es
> nachweist, steht noch aus. Bis dahin entscheidet der Wirtschaftsakteur, wem er Zugang gewährt; BatteryPass stellt
> diese Freigaben nicht als den Zugangsweg der Verordnung dar.