Zum Inhalt springen
TrackJet

tjvt2 · Spezifikation

TrackJet Prüfbare Zeitleiste

Ein manipulationssicheres Siegel für Sendungs-Ereignishistorien. Jedes Ereignis wird beim Erfassen in eine append-only SHA-256-Kette gehasht; jede spätere Änderung, Umsortierung oder Löschung vergangener Ereignisse bricht die Verifikation. Prüfe jede verfolgte Kette unter /verify.

Konstruktion

h(0) = SHA256( "<spec>:" || shipment_uuid || ":" || primary_tracking )
h(n) = SHA256( h(n-1) || canonical(event_n) )          n = 1..N

canonical(event) ist deterministisches JSON mit genau dieser Schlüsselreihenfolge, ohne unbedeutende Leerzeichen, mit unescaptem UTF-8 und Slashes:

{"v":"tjvt2","seq":<n>,"leg_order":<int>,"occurred_at":"<RFC3339>",
 "status":"<string>","description":"<string>","location":<string|null>,
 "country_code":<string|null>,"provenance":"sourced|estimated|declared"}

Ereignisse werden nach (occurred_at, leg_order, Ingest-Index) sortiert — dieselbe stabile Reihenfolge, die die Zeitleisten-UI rendert. seq bindet jedes Ereignis an seine Position, sodass das Vertauschen zweier sonst identischer Ereignisse die Kette ebenfalls bricht.

tjvt2 (aktuell, seit 27.07.2026) fügt provenance als letzten Schlüssel hinzu — die Klasse eines Ereignisses (sourced / estimated / declared) ist damit versiegelt und nicht mehr nachträglich änderbar. tjvt1 (seit 10.06.2026) ist identisch ohne diesen Schlüssel und bleibt dauerhaft prüfbar: Die Spec-Version steht pro Siegel in der Datenbank, nicht im laufenden Code. Eine Kette, die unter tjvt1 begonnen hat, behält ihre tjvt1-Genesis, auch wenn spätere Ereignisse unter tjvt2 versiegelt werden.

Was ein gültiges Ergebnis beweist — und was nicht

  • Beweist: Die heute gespeicherte Ereignishistorie ist byte-identisch mit dem, was TrackJet beim Erfassen aufgezeichnet hat — nichts wurde danach geändert, umsortiert oder gelöscht.
  • Beweist nicht: dass die ursprünglichen Daten des Carriers korrekt waren. Das Siegel deckt TrackJets Aufzeichnung ab dem Erfassen ab, nicht die Realität davor.
  • Siegel werden nach dem Datenbank-Commit geschrieben, append-only. Ereignisse, die vor Sekunden ankamen, können kurz unversiegelt sein („unsealed tail") — das wird als solches gemeldet, nicht als Manipulation.
  • Der Verifizierer und die Proof-API geben nur Integritäts-Metadaten preis (Gültigkeit, Anzahlen, Digests) — nie Ereignisinhalte.

Programmatischer Zugriff

  • GET /api/v1/shipments/{uuid}/proof — Siegel-Liste (nur Hashes) + Verifikations-Urteil (API-Schlüssel nötig; siehe API-Doku).
  • MCP-Server verify_timeline — dasselbe Urteil für KI-Agenten (MCP-Doku).

Aktuelle Spec-Version tjvt2 · Hash-Funktion SHA-256 · tjvt1 veröffentlicht 2026-06-10, tjvt2 am 2026-07-27. Änderungen an der kanonischen Form erhöhen das Versions-Präfix; bestehende Siegel bleiben unter ihrer ursprünglichen Version prüfbar.