PRINTDECKDOCS

Architecture · Chapter 2

Identity and trust

Each kind of actor proves who it is in its own way. No actor has a password. No deck has an AWS key.

2.1 The actors

ActorProofThe service keepsScope
OperatorAWS credentials, on the computer of the owner(AWS IAM)All of the stack and the bucket. Runs pwf: deploys, makes enrollment codes, removes decks (section 1.3).
DeckEd25519 signature on each requestdecks/<id>.json: the public keyThe rights of the owner in the project API. Also the actions that only a deck does: shares, prints, live tiles, owner codes.
OwnerPasskey, then a session tokenowners/<credential>.json: public key, counterAll projects: make, rename, delete, invite, remove members, public address.
MemberPasskey, then a session tokenmembers/<credential>.json: public key, counter, list of projectsThe projects of their passkey: see each one, add photos, move or remove their own photos.
Share ownerThe owner key of one shareThe SHA-256 of the key in shares/<id>.jsonOne share: the Ready flag with a note, and up to 20 photos.
ActionOIDC token of GitHub, a new one for each requestrepos/<owner>/<name>.json: the project of the repository; oidc/<sha256>: the used tokensThe plans and the builds of the one project that links its repository. The token of a member's fork sends the plan of the member's open pull request (section 6.8). Only the workflow printdeck.yml on main or master fills a build (section 6.7).
ViewerKnows the share linkno recordReads the share page and its files until the share ends.
Visitor(none)no recordReads the public page /p/<slug> of a project, when the owner turns it on.

2.2 Deck enrollment

A deck gets its identity once. The owner runs pwf enroll-code on their own computer. The tool uses the AWS credentials of the owner and writes the SHA-256 of a random code to codes/, with the kind "deck" and an expiry of 1 hour. The owner types the code on the deck in Settings, Cloud. The deck makes an Ed25519 key pair and sends the code, its public key and its name. The API deletes the code file and then checks it. So a code works one time, also when the check fails.

Ownerlaptop with pwfDecktouch screenAPILambdaBucketS31pwf enroll-code (AWS credentials)put codes/<sha256>.json: deck, 1 hourshows the codeXXXX-XXXX-XXXXThe owner types the code on the deck: Settings, Cloud, Connect.makes an Ed25519key pair2POST /api/v1/deckscode, public key, name3get and delete the code file4put decks/<id>.json5deck IDsaves cloud.json (0600):domain, deck ID, key seed
Figure 6. Deck enrollment. Step 1 goes from the computer of the owner straight to S3, with the AWS credentials of the owner. The private key never leaves the deck. The bucket keeps only the hash of the code and the public key.

A code has 12 characters from an alphabet of 31 (no 0, O, 1, I or L). That is about 59 bits. The deck keeps its identity in /var/lib/printdeck/cloud.json with mode 0600: the domain, the deck ID, the name and the 32-byte seed of the key. To end the access of a deck, run pwf decks remove ID. Disconnect on the deck also deletes its file at the service and on the deck.

2.3 Signed deck requests

A deck signs each request to the API. The signed text has six lines: a version, the method, the path with its query, the time, a random request ID, and the SHA-256 of the body. The four headers X-Printdeck-* have the deck ID, the time, the request ID and the signature.

The request of the deckPOST /api/v1/sharesX-Printdeck-Deck: <deck ID>X-Printdeck-Time: <Unix seconds>X-Printdeck-Request: <12 random bytes>X-Printdeck-Signature: <Ed25519>{ … JSON body … }The text that the deck signsprintdeck-v1POST/api/v1/shares1793385600<request ID><SHA-256 of the body, hex>Ed25519sign1The deck filedecks/<id>.json exists2The timewithin 5 minutes of the API clock3The signaturevalid for the public key4The request IDnot seen in the last 10 minA failed check gives 401. The API then runs the request with the rights of the deck.
Figure 7. A signed request and the checks of the API (cloud.Verify and Server.deck).

The signature covers the body, so a changed body fails. The time check limits a replay to 10 minutes. Each instance of the function also keeps the request IDs that it saw in that time, and refuses a second use. A new instance starts with no IDs, so this check is partial. TLS is the main guard against a replay.

2.4 Projects and members

A project is x/<id>/project.json, with a random 13-byte ID. It has the members, the open invites, the prints and the share links. The owner makes a project in a browser or on a deck. The owner invites a friend with a first name (section 3.3). The friend joins with a new passkey, or with the passkey from an earlier invite. One passkey of a friend then works for all the projects that the friend joined. The owner can remove a member. The API then 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 that project fails.

Members see the private files of the project through CloudFront, with signed cookies of that project (section 2.7). The bucket stays private, and no member gets a key to it.

A share link shows one print while it runs. A deck makes it after a tap on Make the link. The API makes a share ID and an owner key, and keeps the SHA-256 of the owner key. The deck shows the link with the owner key in the fragment.

https://printdeck.beetlebug.org/s/<share ID>#owner=<owner key>the share pagethe link that viewers get13 random bytesabout 104 bitsthe fragmentthe browser keeps it16 random bytes; the bucket keepsonly its SHA-256
Figure 8. The owner link of a share. A browser does not send the fragment to a server. Copy link on the page gives the address with no owner key.

The page sends the owner key in the header X-Share-Key. The API compares the hash in constant time. The owner key works only for Ready and for photos. The share ends 24 hours after the end of the print, or 24 hours after Ready, whichever is later. The sweep then deletes the share. When the print is in a project, the sweep deletes the files of the share instead, clears the owner key, and makes the page send visitors to the print page. A share with no end goes after 3 days. A lifecycle rule of the bucket also deletes s/ files after 3 days.

Share links are public by design

A share link works for anyone who has it, with no sign-in. Through CloudFront, a viewer reads status.json, ready.json, the camera and time lapse pictures, model.jpg, plan.json and part.bin of the share. The purpose is a print that friends with no account can watch. These things limit the exposure:

  • The share ID has 13 random bytes: 21 characters in the link. CloudFront cannot list the bucket, so the link is the only way to the files.
  • The files of a share have no passkeys, codes, owner keys or member names. They have the print state, the pictures, the printer name, the name of the job, and the Ready note and photos of the owner of the share.
  • The sweep deletes the files 24 hours after the end of the print, or after Ready. A lifecycle rule of the bucket deletes s/ files after 3 days.
  • A share in a project names the project and links to it. The link goes to the public page when the project has one. Otherwise it goes to the project page, which needs a passkey of the project.

Possible future work (not built). Two options came up:

  • Members-only shares: signed cookies on /s/<id>/, in the same way as the files of a project.
  • A choice for each share: public, or members of its project only.

2.6 Upload grants

Large files do not go through the API. The API makes a grant: an S3 POST policy that it signs with the credentials of the function. The deck or the page then sends the file straight to S3. S3 checks the policy and refuses a file that does not obey it.

DeckAPILambdaS3bucket1POST /api/v1/shares/<id>/grantsigned requestsigns a POST policy with theAWS credentials of the function2URL, form fields, prefix, size limit, expiry3POST form: key s/<id>/…, filechecks the policy: signature,expiry, key prefix, size4204, or 403 when a check fails
Figure 9. An upload with a grant. The deck has no AWS key. The policy limits the key prefix, the size and the time.
Grant forKey prefixLargest fileWorks forAsked by
Share filess/<share>/16 MB1 hourthe deck of the share
Share photosup/<share>/<photo>/25 MB15 minthe owner key of the share
Print filesx/<project>/prints/<print>/8 MB1 houra deck
Live picturex/<project>/live/<slot>-<pic>/8 MB1 houra deck
Project photosup/x<project>/<photo>/25 MB15 minthe owner or a member
Plan models and PDFsx/<project>/plans/<plan>/200 MB1 hourthe plan run of the Action
Build filesx/<project>/builds/<build>/200 MB1 hourthe slice run of the Action

A photo goes to up/ first. The API then decodes it and writes new JPEG files with no metadata: no EXIF data, no GPS position and no comments. A test checks this (TestCleanPhotoStripsMetadata). A lifecycle rule deletes files under up/ after 1 day. The CORS rule of the bucket accepts GET and POST only from https://printdeck.beetlebug.org. Uploads use POST with a grant. Reads of project files use the signed cookies, on the same origin. GET serves the signed S3 links, which the API gives when the stack has no cookie key.

2.7 Files of the projects: signed cookies

The files of a project are under x/<project>/: pictures of models, layer plans, time lapse frames, photos and live pictures. CloudFront serves them at the same paths on the domain, under the behavior /x/*. That behavior accepts only requests with a valid CloudFront signed cookie. The bucket policy lets CloudFront read only five patterns under x/:

  • x/*/prints/*/*: the files of a print, such as model.jpg, plan.json and lapse/*.jpg.
  • x/*/photos/*.jpg: the pictures of the photos, also the small copies -s.jpg.
  • x/*/live/*/*: the pictures of the live tiles.
  • x/*/plans/*/*: the models of a plan, as STL files for the 3D views of the plan page, and the PDFs of the plan with a picture of each first page.
  • x/*/builds/*/*: the sliced files of a build.

The JSON records stay with the API: project.json, prints/<id>.json, photos/<id>.json, live/<slot>.json, plans/<id>.json and builds/<id>.json. CloudFront cannot read them, also with a valid cookie.

Browserapp pageAPILambdaCloudFront/x/* behaviorS3bucket1GET /api/v1/projects/<id>Authorization: Bearer <token>checks the session; the viewlinks to /x/<id>/… pathssigns a policy forhttps://<domain>/x/<id>/*, 1 hour2view + 3 cookies: CloudFront-Policy,-Signature, -Key-Pair-Id; Path /x/<id>/3GET /x/<id>/prints/…/model.jpgthe browser adds the cookies of the pathchecks the signature with thekey group, the resource, the time4GET with OAC (or the edge cache)5the file6200Another project, or no cookie7GET /x/<other>/…: no cookie of that path8403, shown as the not found page (404)
Figure 10. The signed cookies of the files of a project. The cookies of one project do not open the files of another project.
  1. An API reply that links to files of a project gives the paths /x/<project>/… in place of signed S3 links. These replies are the project list (cover pictures), the project view with its live tiles and its PDFs, the view in the reply of GET /api/v1/names/<slug>?view=1, the time lapse frames of a print, a plan with its models and PDFs, and a build.
  2. The API notes each project of the links. For each one, it signs a custom policy with the resource https://<domain>/x/<project>/* and an expiry of one hour. The signature is RSA with SHA-1, as CloudFront requires.
  3. The reply sets three cookies for each project: CloudFront-Policy, CloudFront-Signature and CloudFront-Key-Pair-Id. Each has Path=/x/<project>/, Secure, HttpOnly, SameSite=Lax and an expiry of one hour. The Lambda function sends them in the cookie list of the function URL reply, because the headers keep only one Set-Cookie.
  4. The browser sends the cookies only with requests under that path. CloudFront checks the signature with the public key in the key group <stack>-files, the resource and the time. Then it reads the file from S3 with OAC, or from its edge cache.

The owner tested the live service. A request with no cookie gets 404. With the cookie of the project, plan.json, model.jpg and photo pictures get 200, and project.json, prints/<id>.json and photos/<id>.json get 404. The same cookie on another project gets 404. The private key is in the secret <stack>-files-key. The function reads it at its start (FILES_KEY_SECRET, FILES_KEY_ID), at the same time as the secrets of the GitHub App and of the relay. When the stack has no key, the API gives signed S3 links for one hour, as before. A deck has no cookies, so the API always gives a deck a signed S3 link of one hour for each plate file that waits for it.

2.8 Who can do what

ActionDeckOwnerMemberShare ownerViewer
Make a share link, upload its files✓····
See a share page✓✓✓✓✓
Mark a share Ready, add share photos✓··✓·
Ask for an owner code✓····
Make, rename or delete a project✓✓···
Invite a friend, remove a member✓✓···
Turn the public address on or off✓✓···
See a project and its files✓✓own projects··
Add a photo to a project✓✓own projects··
Remove a photo✓✓own photos··
Move a photo to another print✓✓own photos··
Take a file out of the queue of a printer✓✓···
Add a print or a live tile✓····
Remove a print✓✓···
Rename a print, mark it Delivered, In use or Rejected, set its source·✓···
Write the notes of a project or a print·✓own projects··
See the plans and the builds·✓own projects··
Set the GitHub username of a member✓✓···
Link a repository, slice, approve, reject or send a plate✓✓···

"Own projects" means the projects of the passkey of the member that still have the member. The API refuses a member session for another project with 401. "Own" photos are the photos that the member added. A deck gets the rights of the owner in the project API, so ownerOnly also accepts a deck. The routes that show a plan, a build or the notes refuse a deck.

Back: 1 OverviewContentsNext: 3 Passkey flows