PRINTDECKDOCS

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: owner for the owner, and m:<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.

Decktouch screenOwner's phonepage /ownerAuthenticatorpasskey storeAPILambdaBucketS31POST /api/v1/owner/code (signed)2put codes/<sha256>.json: owner, 10 min3code, URL /owner#code=…shows the URLas a QR codeThe owner scans the QR code. The code is in the fragment.4POST auth/owner/begin: code5read the code (keep it); list owners/6options (challenge, RP ID), sealed state7navigator.credentials.create()8new key pair, public key9POST auth/owner/finishstate, credential, code, nameopen the state; checkchallenge, origin, RP ID10delete the code; putowners/<credential>.json11session token (owner, 14 days)
Figure 11. Owner enrollment. The orange steps change the stored identity. The owner can repeat this for each device. Each device then has its own passkey file.

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.

Ownerproject pageFriendpage /jAuthenticatorof the friendAPILambdaBucketS3signed in (owner)1POST projects/<id>/invitesfirst name, owner session2project.json: member, hash of code;put invites/<sha256>.json (7 days)3member ID, link /j#<code>, expiryCopy or Share;sends the link4POST invites/view: code5owner name, project name, first namefirst name; tap Joinwith a new passkey6POST auth/invite/begin: code7options; state with SHA-256 of code8credentials.create()9new key pair10POST auth/invite/finishstate, credential, code, name11delete the invite; member joins;put members/<credential>.json12session token (member of this project)opens /projectsA friend with a passkey: Join with my passkey (next figure). Later visits: section 3.4
Figure 12. The invite workflow with a new passkey, from the invite to the first session of the friend. The orange steps change the stored identity.

The steps

  1. The owner signs in with the owner passkey and opens the project page /projects/<slug>.
  2. Under Friends, the owner types the first name of the friend and sends the form.
  3. The page sends POST /api/v1/projects/<id>/invites with the first name and the owner session. Only the owner can do this.
  4. The API makes a code and a member ID. It adds a member to project.json with the first name, the time of the invite and the SHA-256 of the code. It writes invites/<sha256>.json with the project, the member, the name and the expiry (7 days). A project has at most 50 members and invites.
  5. 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.
  6. The owner sends the link to the friend on any channel.
  7. 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.
  8. The friend taps Join with a new passkey. The page sends auth/invite/begin with the code. The API gives the options of a new passkey and a sealed state with the SHA-256 of the code.
  9. The browser makes the passkey for printdeck.beetlebug.org. The user handle is m:<project>:<member>.
  10. The page sends auth/invite/finish with 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.
  11. 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 writes members/<credential>.json with the user handle and a list of projects with this one project.
  12. 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.
  13. For later visits, the friend signs in with login/begin and login/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.

Friendpage /j#<code>Authenticatorof the friendAPILambdaBucketS3taps Join with my passkey1POST auth/login/begin2options; sealed state (5 min)3credentials.get()4assertion, user handle5POST auth/login/finishstate, assertion, code, namecheck the passkey; read the inviteowner passkey: 400 · bad code: 410joinWith: project on the passkey?yes: 409, the invite stays6delete the invite; member joins;add the project to the passkey file7session token (all projects of the passkey)opens /projects:the list of projects
Figure 13. Join with my passkey. The sign-in adds the project of the invite to the passkey. The orange steps change the stored identity.
  1. The page sends auth/login/begin. The API gives the options of a sign-in and a sealed state.
  2. The browser calls navigator.credentials.get(). The friend picks the passkey for printdeck.beetlebug.org.
  3. The page sends auth/login/finish with the state, the assertion, the invite code and the first name.
  4. The API checks the passkey as in each sign-in (section 3.4), and stores the new counter.
  5. An owner passkey with an invite code gets 400. The API reads the invite. A code that is used, removed or expired gets 410.
  6. The API runs joinWith. A passkey that has the project already gets 409, and the invite stays.
  7. Otherwise, joinWith deletes 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.
  8. 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 canA member cannot
  • See each project of their passkey: the prints, the live tiles, the time lapses and the photos. The files come with the signed cookies of each project, for one hour at a time.
  • See the names of the members that joined.
  • Add photos to the project or to a print.
  • Remove the photos that they added, or move them to another print.
  • Write the notes of the project and of each print.
  • See the plans and the builds from GitHub, with no keys to change them.
  • See a project that they did not join. The API refuses it with 401.
  • See the open invites of the project.
  • Rename or delete the project, or change its public address.
  • Invite friends or remove members.
  • Remove prints, the photos of other people, or a file from the queue of a printer.
  • Rename a print, mark it Test, Ready, Delivered, In use or Rejected, or set the link to its source.
  • Link a repository, slice a plan, or approve or reject a plate.

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.

Browserapp pageAuthenticatorpasskey storeAPILambdaBucketS31POST auth/login/begin2options: challenge, RP ID;sealed state (5 min)3navigator.credentials.get()person picks a passkey;signs challenge + origin4assertion, user handle5POST auth/login/finishstate, assertionopen the state; user handleowner → owners/, else members/6get the passkey filecheck handle, signature,challenge, origin, flags7put the new counter8session token (14 days): owner, ormember of each project of the passkey
Figure 14. Sign-in. A passkey with no file fails with 401: an owner passkey that the operator deleted, or a member passkey with no project left.

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.

The session tokenbase64url( JSON of the claims ).base64url( HMAC-SHA-256 ){"k":"member","ms":{"<project>":"<member>","<project>":"<member>"},"e":1793429000}k: owner or member · ms: each project and the member ID in it · e: expiry, Unix secondsHMAC key: keys/session (32 bytes) · input: "session", a zero byte, the JSONAuthorization:Bearer <token>401: no headerHMACequal (constant time)401Expirynow ≤ e401Memberin the project (whoFor)401runThe member check reads the project at each request on it. A removed member gets 401 at once.
Figure 15. The session token and the checks of each request (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.

One key, two purposes"session"session claimsworks for 14 days · goes in the Authorization: Bearer"ceremony"WebAuthn session data: challenge, user; purpose owner, invite or login; invite hashworks for 5 minutes · goes in the JSON field stateThe purpose goes into the HMAC. A ceremony state does not open as a session, and a session does not open as a state.
Figure 16. Two kinds of sealed token with one key.

Back: 2 Identity and trustContentsNext: 4 Why it is secure