README.md

Zuauth

A simple package designed to streamline the development of a zero-knowledge authentication system with Zupass tickets.

The repository includes the zuauth package along with a documented example demonstrating how to create an authentication system using NextJS and IronSession. Use the demo and refer to the tutorial section below to understand how to integrate zuauth into your app.

🛠 Install

Install the zuauth package with npm:

npm i zuauth

or yarn:

yarn add zuauth

📜 Tutorial

Note

The example in the repository uses iron-session to manage sessions, but you are of course free to integrate your preferred solution.

Server

First, you need to create the server-side logic to generate a session nonce and perform the authentication. The example in this repository includes four functions: login, logout, nonce, and user. Remember to add all necessary checks in your login function, particularly ensuring that the ticket has been issued by Zupass and that it is among the supported tickets.

Client

Next, you can proceed with the client side.

1. Create a page for the Zupass popup:

zuauth/example/src/pages/popup.tsx

Lines 1 to 10 in c7c052a

	import { usePopup } from "zuauth"
	/**
	* This popup sends requests and receives PCDs from the passport.
	*/
	export default function Popup() {
	const error = usePopup()
	return <div>{error}</div>
	}

2. Create another page and define the default set of ticket fields to reveal.

zuauth/example/src/pages/index.tsx

Lines 11 to 23 in c7c052a

	const defaultSetOfTicketFieldsToReveal: EdDSATicketFieldsToReveal = {
	revealTicketId: false,
	revealEventId: true,
	revealProductId: true,
	revealTimestampConsumed: false,
	revealTimestampSigned: false,
	revealAttendeeSemaphoreId: false,
	revealIsConsumed: false,
	revealIsRevoked: false,
	revealTicketCategory: false,
	revealAttendeeEmail: true,
	revealAttendeeName: false
	}

3. Check if the user is logged-in.

zuauth/example/src/pages/index.tsx

Lines 26 to 45 in c7c052a

	const { authenticate, pcd } = useZuAuth()
	const [user, setUser] = useState<any>()
	const [developerMode, setDeveloperMode] = useState(false);
	const [ticketFieldsToReveal, setTicketFieldsToReveal] = useState<EdDSATicketFieldsToReveal>(defaultSetOfTicketFieldsToReveal);
	// Every time the page loads, an API call is made to check if the
	// user is logged in and, if they are, to retrieve the current session's user data
	// and local storage data (to guarantee consistency across refreshes).
	useEffect(() => {
	; (async function () {
	const { data } = await axios.get("/api/user")
	setUser(data.user)
	const fields = localStorage.getItem("ticketFieldsToReveal");
	const mode = localStorage.getItem("developerMode")
	if (fields) setTicketFieldsToReveal(JSON.parse(fields));
	if (mode) setDeveloperMode(JSON.parse(mode))
	})()
	}, [])

4. Create a function to login, which generates a nonce and user's PCD:

zuauth/example/src/pages/index.tsx

Lines 58 to 70 in c7c052a

	// Before logging in, the PCD is generated with the nonce from the
	// session created on the server.
	// Note that the nonce is used as a watermark for the PCD. Therefore,
	// it will be necessary on the server side to verify that the PCD's
	// watermark matches the session nonce.
	const login = async () => {
	const { data } = await axios.post("/api/nonce")
	authenticate(
	developerMode ? { ...ticketFieldsToReveal } : { ...defaultSetOfTicketFieldsToReveal },
	data.nonce
	)
	}

5. Check when the PCD is generated and returned by the Zupass popup to call the login API:

zuauth/example/src/pages/index.tsx

Lines 47 to 56 in c7c052a

	// When the popup is closed and the user successfully
	// generates the PCD, they can login.
	useEffect(() => {
	; (async function () {
	if (pcd) {
	const { data } = await axios.post("/api/login", { pcd })
	setUser(data.user)
	}
	})()
	}, [pcd])

Important

When the user interacts with the Zupass popup, the output, which is the generated PCD, is not returned by any function but can be found in the pcd state variable within the useZuAuth hook. It's important to check if the value is defined.

6. Create a function to allow users to log out:

zuauth/example/src/pages/index.tsx

Lines 72 to 82 in c7c052a

	// Logging out simply clears the active session, local storage and state.
	const logout = async () => {
	await axios.post("/api/logout")
	setUser(false)
	localStorage.removeItem("ticketFieldsToReveal")
	localStorage.removeItem("developerMode")
	setTicketFieldsToReveal(defaultSetOfTicketFieldsToReveal)
	setDeveloperMode(false)
	}

7. Create your UI:

zuauth/example/src/pages/index.tsx

Lines 161 to 194 in c7c052a

	<div className="my-8 text-center">
	<button
	className="bg-blue-800 hover:bg-blue-900 text-white font-bold py-2 px-4 rounded"
	onClick={!user ? login : logout}
	>
	{!user ? "Login" : "Log out"}
	</button>
	</div>
	{!user &&
	<>
	<div className="my-8 text-center flex flex-col items-center">
	<p className="mt-2 text-center">Developer Mode</p>
	<Toggle
	checked={developerMode}
	onToggle={handleSetDeveloperMode}
	/>
	</div>
	<div style={{ height: "300px" }}>
	{developerMode && (
	<DeveloperPanel
	fieldsToReveal={ticketFieldsToReveal}
	onToggleField={handleToggleField}
	disabled={!!user}
	/>
	)}
	</div>
	</>
	}
	{user && <div className="my-8 text-center">
	<DisplayRevealedFields user={user} revealedFields={ticketFieldsToReveal} /> </div>}
	</div>