Praticable Ticket Protocol (PTP)

Dit protocol definieert hoe een scanner een ticket valideert dat is uitgegeven door een onafhankelijke issuer. Issuers coördineren niet met elkaar en vereisen geen centrale autoriteit.

Het protocol is ontworpen met vier doelstellingen:

• Offline verificatie van de authenticiteit van tickets via cryptografische signatures
• Online check-in status met sterke consistentie om dubbel scannen te voorkomen
• Onafhankelijkheid van issuers: issuers coördineren niet met elkaar
• Key rotation zonder reeds uitgegeven tickets ongeldig te maken

Het signature-algoritme is Ed25519 (RFC 8032). De signatures van 64 bytes zijn compact genoeg om in een QR-code te passen naast de payload-gegevens, en verificatie is snel dankzij native ondersteuning in de Web Crypto API.

Levenscyclus van sleutels

Elke issuer genereert een sleutelpaar bij de inrichting. De private key wordt opgeslagen in de Worker secrets en verlaat nooit de issuer. De public key wordt gepubliceerd op het well-known endpoint. Meerdere actieve public keys kunnen naast elkaar bestaan tijdens rotatieperioden.

Sleutelidentificatie (kid)

Elke public key heeft een korte, unieke identificatie: de eerste 8 hexadecimale tekens van de SHA-256-hash van de ruwe public key. Payloads verwijzen naar de kid zodat scanners weten welke sleutel zij voor verificatie moeten gebruiken.

De QR-code bevat een compacte JSON-payload gecodeerd in base64url, gevolgd door de signature. Het voorvoegsel tkt1. identificeert de protocolversie en onderscheidt ticket-QR-codes van andere codes die een scanner kan tegenkomen.

tkt1.<base64url(payload_json)>.<base64url(signature)>

JSON-structuur van de payload

{
  "v": 1,
  "iss": "https://tickets.example.com",
  "kid": "a1b2c3d4",
  "tid": "01HXXX...ULID",
  "eid": "evt_01HXXX...ULID",
  "ev": {
    "name": "Gala Concert",
    "date": "2026-06-15T20:00:00Z",
    "venue": "Royal Hall"
  },
  "tt": "VIP",
  "hn": "J. Smith",
  "iat": 1745000000,
  "exp": 1765000000
}

Signature

De signature wordt berekend over de exacte bytevolgorde van de base64url-gecodeerde payload (vóór het tweede .-scheidingsteken), met de Ed25519 private key van de issuer. Scanners verifiëren door de signature opnieuw te berekenen over dezelfde bytes.

Elke issuer MOET een discovery-document publiceren op het volgende adres:

{
  "protocol_version": 1,
  "issuer": "https://tickets.example.com",
  "name": "Client business name",
  "keys": [
    {
      "kid": "a1b2c3d4",
      "alg": "Ed25519",
      "public_key": "base64url-encoded-raw-32-byte-public-key",
      "valid_from": "2026-01-01T00:00:00Z",
      "valid_until": null
    }
  ],
  "endpoints": {
    "check_in": "https://tickets.example.com/api/v1/tickets/check-in",
    "status": "https://tickets.example.com/api/v1/tickets/{tid}/status",
    "scanner_enroll": "https://tickets.example.com/api/v1/scanners/enroll"
  },
  "supported_versions": [1]
}

• keys KAN meerdere items bevatten tijdens rotatie. Scanners moeten elke niet-verlopen sleutel accepteren waarvan de kid overeenkomt met de payload.
• valid_until: null betekent momenteel actief zonder geplande vervaldatum.
• Scanners MOETEN dit document cachen met een TTL van maximaal 1 uur, en MOETEN het opnieuw ophalen als verificatie mislukt met een onbekende kid.

Scanners worden geregistreerd voor een evenement door het scannen van een tijdgebonden setup QR-code die is gegenereerd via de beheerdersinterface van de organisator. De setup QR bevat een enrollment token die de scanner bij eerste gebruik inwisselt voor een langlevende API key, beperkt tot een of meer evenementen.

tsetup1.<base64url(setup_json)>

Het voorvoegsel tsetup1. onderscheidt setup QR-codes van ticket QR-codes (tkt1.).

{
  "v": 1,
  "iss": "https://tickets.example.com",
  "enroll_url": "https://tickets.example.com/api/v1/scanners/enroll",
  "token": "st_01HXXX...opaque-enrollment-token",
  "eid": "evt_01HXXX...ULID",
  "event_name": "Gala Concert",
  "gate_id": "north",
  "expires_at": "2026-06-16T02:00:00Z"
}

Mogelijkheden van de scanner

Een scanner KAN actieve enrollments voor meerdere evenementen tegelijkertijd bevatten. Dit ondersteunt locaties met meerdere fases, opeenvolgende evenementen en festivals. Elke enrollment voegt een evenement toe aan de actieve set van de scanner zonder eerdere enrollments te vervangen.

Levenscyclus van API keys

• Scope: elke API key is gekoppeld aan precies een evenement (en optioneel een gate). Een scanner die voor meerdere evenementen is geregistreerd, beschikt over meerdere API keys.
• Vervaldatum: API keys verlopen op het expires_at-tijdstempel dat in de enrollment-response wordt teruggegeven (doorgaans einde evenement + marge). Verlopen keys worden afgewezen met UNAUTHORIZED.
• Intrekking: organisatoren kunnen een key op elk moment intrekken via de beheerdersinterface.
• Geen vernieuwing: als een API key tijdens een evenement verloopt, moet de scanner opnieuw worden geregistreerd via een nieuwe setup QR.
• Rotatie: om een gecompromitteerde key te vervangen, trekt de organisator de oude key in en geeft een nieuwe setup QR uit.

Wanneer een ticket wordt gescand, MOET de scanner het bijbehorende evenement automatisch detecteren door het veld eid uit de geverifieerde payload te lezen. De operator selecteert geen evenement handmatig. Hier is de verwerkingsvolgorde:

Het voorkomen van dubbel scannen wordt afgedwongen door de issuer via een Durable Object dat per evenement is afgebakend. Alle check-in-schrijfbewerkingen voor een bepaald evenement worden geserialiseerd via dit DO, waardoor precies een check-in slaagt, zelfs bij gelijktijdige requests van meerdere gates.

Scanners MOETEN kunnen functioneren met wisselende connectiviteit. Hier is de verwerkingsvolgorde voor elke scan:

Issuers MOETEN check-in requests accepteren met scanned_at-tijdstempels in het verleden (tot een redelijk venster, bijv. 48 uur) om in de wachtrij geplaatste offline scans te ondersteunen.

• Verplichte signature-verificatie voordat enige payload-inhoud wordt vertrouwd. Toon nooit houdernamen of evenementinformatie zonder eerst de signature te hebben geverifieerd.
• Tijdsvalidatie: scanners MOETEN tickets afwijzen waarvan exp op het moment van scannen in het verleden ligt, en MOETEN waarschuwen bij onwaarschijnlijk toekomstige iat-tijdstempels.
• Validatie van issuer-URL: het veld iss is een URL. Scanners MOETEN HTTPS afdwingen en MOETEN zich beperken tot een vertrouwenslijst van issuer-domeinen als de context dat vereist.
• Opslag van API keys: scannerapplicaties MOETEN API keys opslaan in de beveiligde opslag van het platform (Keychain, Keystore).
• Rate limiting: issuers MOETEN check-in endpoints per scannercredential beperken om misbruik te voorkomen.
• TLS: alle endpoints MOETEN worden aangeboden via TLS 1.2+. HTTP-naar-HTTPS-doorverwijzingen zijn niet voldoende voor API-aanroepen.
• Replay-bescherming: de idempotency_key voorkomt onbedoelde replay. Opzettelijke replay met een nieuwe key wordt gedetecteerd door de server-side tid-status en retourneert already_used.

Enrollment-beveiliging

• Vertrouwelijkheid van de setup QR: de setup QR is een bearer credential totdat deze is verbruikt. Deze MOET worden gegenereerd vlak voor het uitdelen van apparaten aan personeel, alleen worden weergegeven op vertrouwde schermen, en niet worden gefotografeerd of gedeeld via chat/e-mail.
• Token-entropie: tokens MOETEN ten minste 128 bits entropie bevatten van een cryptografisch veilige RNG.
• Rate limiting: het scanner_enroll endpoint MOET worden beperkt per IP en per token.
• Verplicht TLS: scanners MOETEN elke setup QR afwijzen waarvan iss of enroll_url geen HTTPS is.
• Bevestiging door operator: de scanner MOET de event_name, datum en issuernaam tonen, en uitdrukkelijke bevestiging vragen voordat het enrollment endpoint wordt aangeroepen.
• Auditspoor: issuers MOETEN elke enrollment-poging loggen (geslaagd en mislukt).

• Het veld v in payloads en het veld protocol_version in het discovery-document bevatten de hoofdversie.
• Kleine toevoegingen (nieuwe optionele velden) verhogen de hoofdversie niet. Scanners MOETEN onbekende velden negeren.
• Ingrijpende wijzigingen verhogen de hoofdversie. Issuers MOETEN de vorige versie blijven accepteren gedurende een redelijke overgangsperiode (bijv. 6 maanden).