Architecture · Chapter 3
Passkey flows
People sign in with passkeys (WebAuthn). The service keeps no passwords and no email addresses.
3.1 The settings of the passkeys
- Relying party ID:
printdeck.beetlebug.org, the host name of the service. The browser makes and uses each passkey for this domain only. - Origin:
https://printdeck.beetlebug.org. The API refuses a credential that a page of another origin made. - Discoverable keys: registration requires a resident key. So the sign-in needs no user name: the authenticator gives the credential ID and the user handle.
- User verification: "preferred". The authenticator asks for a PIN or a biometric when it can.
- User handles:
ownerfor the owner, andm:<project>:<member>for a member, from the project of its first invite.
Each ceremony has two requests: begin gives the options and a sealed state, and finish sends the state back with the credential. The API keeps no state between the two (section 3.6).
3.2 Owner enrollment
An enrolled deck asks for an owner code with a signed request. The code works for 10 minutes. The deck shows the page /owner#code=<code> as a QR code. The owner scans it with a phone and makes a passkey. Begin only reads the code. Finish deletes the code, and then stores the passkey. Begin also lists the passkeys of the owner as exclusions, so one authenticator does not get a second owner passkey.
3.3 The invite workflow
The owner invites a friend to a project. The friend gets a link and joins with a passkey. A friend with no passkey for Printdeck makes a new passkey with the link. A friend with a passkey from an earlier invite signs in with it, and the API adds the project to that passkey. The code of the link has 16 random bytes (128 bits). The API keeps only its SHA-256. The invite works for 7 days and works once.
The steps
- The owner signs in with the owner passkey and opens the project page
/projects/<slug>. - Under Friends, the owner types the first name of the friend and sends the form.
- The page sends
POST /api/v1/projects/<id>/inviteswith the first name and the owner session. Only the owner can do this. - The API makes a code and a member ID. It adds a member to
project.jsonwith the first name, the time of the invite and the SHA-256 of the code. It writesinvites/<sha256>.jsonwith the project, the member, the name and the expiry (7 days). A project has at most 50 members and invites. - The API replies with the member ID, the link
https://printdeck.beetlebug.org/j#<code>and the expiry. The page shows the link with Copy, and with Share when the browser has a share sheet. - The owner sends the link to the friend on any channel.
- The friend opens the link. The page reads the code from the fragment and sends
POST /api/v1/invites/view. The reply has the name of the owner, the name of the project and the first name. The page shows "<owner> invited you to <project>", with the first name in a field that the friend can change. - The friend taps Join with a new passkey. The page sends
auth/invite/beginwith the code. The API gives the options of a new passkey and a sealed state with the SHA-256 of the code. - The browser makes the passkey for
printdeck.beetlebug.org. The user handle ism:<project>:<member>. - The page sends
auth/invite/finishwith the state, the credential, the code and the first name. The API checks that the state has the hash of this code, reads the invite again, and checks the credential. - The API runs
join: it deletes the invite file, sets the time of the join on the member, clears the code hash, and adds the passkey file to the member. It writesmembers/<credential>.jsonwith the user handle and a list of projects with this one project. - The API replies with a session token for a member of this project. The page keeps it and opens
/projects, where the friend sees the project. - For later visits, the friend signs in with
login/beginandlogin/finish(section 3.4).
Join with my passkey
A friend with a passkey from an earlier invite taps Join with my passkey. This is a sign-in with the invite code. The page shows this choice first when the tab has a member session. The passkey keeps its user handle from the first invite.
- The page sends
auth/login/begin. The API gives the options of a sign-in and a sealed state. - The browser calls
navigator.credentials.get(). The friend picks the passkey forprintdeck.beetlebug.org. - The page sends
auth/login/finishwith the state, the assertion, the invite code and the first name. - The API checks the passkey as in each sign-in (section 3.4), and stores the new counter.
- An owner passkey with an invite code gets 400. The API reads the invite. A code that is used, removed or expired gets 410.
- The API runs
joinWith. A passkey that has the project already gets 409, and the invite stays. - Otherwise,
joinWithdeletes the invite file, sets the time of the join on the member, and clears the code hash. It adds the passkey file to the member, and adds the project to the list of the passkey. - The API replies with a session token for all the projects of the passkey. The page opens
/projects, where the friend sees the list.
What the owner sees
The project page lists each member for the owner. A member that did not join yet shows "invited" and the day of the invite. A member that joined shows "joined". Each row has Remove. Remove on an open invite deletes the invite file, so the link stops working. Remove on a member deletes the member from project.json. Then leaveKey removes the project from each passkey of the member. It deletes a passkey file only when no project is left on it. The next request of the member on this project gets 401. The other projects of the passkey still work. A delete of a project does the same for each member of the project.
A code that does not work
The API replies 410 to a code that is used, removed or expired, and to a code with a wrong form. invites/view, invite/begin, invite/finish and login/finish with a code all check the code. The page then shows "This invite does not work" and asks the friend to ask for a new invite. A lifecycle rule also deletes the invite files after 8 days.
What a member can do
| A member can | A member cannot |
|---|---|
|
|
The API reads the session into a who value: owner, or member. whoFor finds the member ID of the session in the project of the request. Then it loads the project and checks that the project still has that member. ownerOnly guards each owner action. viewProject gives a member only the members that joined.
3.4 Sign-in
The owner and the members sign in on the same page with the same two requests. The API finds the passkey file from the user handle and the credential ID. The user handle in the assertion must match the handle of the file. The library checks the signature with the stored public key, and checks the challenge, the origin, the RP ID and the flags. The API then stores the new signature counter.
A member passkey has a list of projects. The session of a member has all of them, each with the member ID in that project. The reply names the project only when the passkey has one project. The page then opens that project. With more projects, the page shows the list. GET /api/v1/projects lists each project of the session that still has the member.
A passkey file from before commit e1fcfca has one project and one member. Passkey.normalize reads them as a list of one project. Each sign-in writes the file for the counter, so the file then has the list.
3.5 The session token
A sign-in, an owner enrollment and a join each give a session token. The token is the JSON of the claims and an HMAC-SHA-256 of them. The key is keys/session: 32 random bytes that the API makes at the first use. The page keeps the token and its expiry in localStorage, so the sign-in stays after the tab closes. A 401 also removes it. The page sends it in the header Authorization: Bearer <token>. Sign out clears the stored token on the page.
The claims of a member have ms, a map from each project to the member ID in it. A token from before commit e1fcfca has one project in p and m. The API still accepts it until it expires, after at most 12 hours. session loads no project. whoFor checks the member in the project of each request, so a removal works at once.
Server.session, then whoFor for a request on a project). A session works for 14 days.3.6 Sealed ceremony state
The WebAuthn library gives session data at begin: the challenge and the user. The API seals it with the same HMAC key and gives it to the page. At finish, the API opens it and checks the purpose and the expiry of 5 minutes. A page cannot change the challenge, because the HMAC then fails. So any instance of the function can finish a ceremony that another instance began, and the bucket keeps no ceremony files.