Zupass

Introduction

This document outlines the technical specifications and integration steps between ZuPass, a ticket management platform, and Lemonade, an event management system. The integration enables listing and validating tickets for events managed within Lemonade through the ZuPass platform using Zero-Knowledge Proof (ZK) cryptography and OAuth2 for client authentication.

System Overview

The system is divided into two main parts, ZuPass and Lemonade, each hosting a series of applications and services that interact with each other to facilitate ticket listing and check-in functionalities.

ZuPass Components

• ZuPass Web App: The frontend interface for users to manage their tickets (https://zupass.org).

• ZuPass Backend App: The server-side application handling ticket encryption and communication with Lemonade.

Lemonade Components

• Lemonade ZuPass Feed Server: The service that provides ticket data to ZuPass.

  • repo: https://github.com/lemonadesocial/lemonade-zupass

  • deployed at: https://zupass.lemonade.social/tickets

• Lemonade Backend Server: A GraphQL server that manages event data and user check-ins.

  • repo: https://github.com/lemonadesocial/lemonade-backend

  • deployed: at: https://backend.lemonade.social

• Lemonade Admin API: An internal API for privileged operations within Lemonade's infrastructure.

Authentication and Security

• Zero-Knowledge Proof (ZK): Explains the cryptographic principles behind ZK and how it is applied within ZuPass to handle ticket data securely.

• OAuth2 Client Authentication: Details the OAuth2 protocol used for secure server-to-server communication between ZuPass and Lemonade.

Integration Flows

Listing Tickets on ZuPass

1. User Authentication: The user logs in to ZuPass with their email address and verifies it.

2. Subscription to Lemonade: The user adds a new subscription and inputs the URL of the Lemonade feed server into the corresponding input box.

3. Ticket Retrieval: A new folder named "Lemonade" is created, containing all the tickets that the user has across all events on Lemonade.

Check-in Process with ZuPass

1. Accessing Tickets: The user navigates to the "Lemonade" folder within the ZuPass web application and clicks on the ticket they wish to use for event entry.

2. QR Code Generation: The ZuPass web application displays a QR code corresponding to the selected ticket. This QR code may be presented in Zero-Knowledge (ZK) mode or non-ZK mode, depending on the security requirements.

3. Ticket Presentation: The user presents this QR code to the ZuPass ticket scanner at the event. This scanner is operated by the event host and can be a smartphone or any other device capable of scanning QR codes.

4. Validation Feedback: ZuPass immediately informs the user whether the ticket is valid.

How the System Works for User Check-In:

1. QR Code Generation: Upon a ticket being selected in the ZuPass web application, cryptographic algorithms are executed to generate a QR code for the user's ticket.

2. QR Code Scanning: This QR code is scanned by the event host using the ZuPass scanner application, which then transmits the scanned data to the ZuPass backend server.

3. Authentication with Lemonade GraphQL Server: The ZuPass backend server employs OAuth2 client-credentials flow to establish a secure authentication session with the Lemonade GraphQL server.

   • Credential Association: The OAuth2 credentials utilized during this process are linked to a specific ZuPass user account that is stored within the Lemonade backend database.

   • Event Access Authorization: For authorization to manage event access and ticketing, the ZuPass user account associated with the OAuth2 credentials must be designated as a co-host for the respective events.

4. API Interaction for Check-In: The ZuPass backend server makes an API call to the Lemonade GraphQL server to register the user's check-in.

5. Server Response: Upon successful check-in, the Lemonade GraphQL server issues a 200 OK status code; alternatively, it sends an error code if the process encounters any issues.

6. Outcome Communication: The result of the check-in process, whether successful or not, is then conveyed by the ZuPass backend server to the scanner device to inform the user of their check-in status.