Skip to content
/ zuauth Public

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

License

Notifications You must be signed in to change notification settings

cedoor/zuauth

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

31 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ZuAuth Icon Zuauth

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

Github license NPM version

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:

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>
}

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

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
}

  1. Check if the user is logged-in.

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))
})()
}, [])

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

// 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
)
}

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

// 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.

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

// 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)
}

  1. Create your UI:

<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>

About

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

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published