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
| Actor | Proof | The service keeps | Scope |
|---|---|---|---|
| Operator | AWS 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). |
| Deck | Ed25519 signature on each request | decks/<id>.json: the public key | The rights of the owner in the project API. Also the actions that only a deck does: shares, prints, live tiles, owner codes. |
| Owner | Passkey, then a session token | owners/<credential>.json: public key, counter | All projects: make, rename, delete, invite, remove members, public address. |
| Member | Passkey, then a session token | members/<credential>.json: public key, counter, list of projects | The projects of their passkey: see each one, add photos, move or remove their own photos. |
| Share owner | The owner key of one share | The SHA-256 of the key in shares/<id>.json | One share: the Ready flag with a note, and up to 20 photos. |
| Action | OIDC token of GitHub, a new one for each request | repos/<owner>/<name>.json: the project of the repository; oidc/<sha256>: the used tokens | The 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). |
| Viewer | Knows the share link | no record | Reads the share page and its files until the share ends. |
| Visitor | (none) | no record | Reads 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.
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.
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.
2.5 Share links and the owner key
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.
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.
| Grant for | Key prefix | Largest file | Works for | Asked by |
|---|---|---|---|---|
| Share files | s/<share>/ | 16 MB | 1 hour | the deck of the share |
| Share photos | up/<share>/<photo>/ | 25 MB | 15 min | the owner key of the share |
| Print files | x/<project>/prints/<print>/ | 8 MB | 1 hour | a deck |
| Live picture | x/<project>/live/<slot>-<pic>/ | 8 MB | 1 hour | a deck |
| Project photos | up/x<project>/<photo>/ | 25 MB | 15 min | the owner or a member |
| Plan models and PDFs | x/<project>/plans/<plan>/ | 200 MB | 1 hour | the plan run of the Action |
| Build files | x/<project>/builds/<build>/ | 200 MB | 1 hour | the 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 asmodel.jpg,plan.jsonandlapse/*.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.
- 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 ofGET /api/v1/names/<slug>?view=1, the time lapse frames of a print, a plan with its models and PDFs, and a build. - 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. - The reply sets three cookies for each project:
CloudFront-Policy,CloudFront-SignatureandCloudFront-Key-Pair-Id. Each hasPath=/x/<project>/,Secure,HttpOnly,SameSite=Laxand an expiry of one hour. The Lambda function sends them in the cookie list of the function URL reply, because the headers keep only oneSet-Cookie. - 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
| Action | Deck | Owner | Member | Share owner | Viewer |
|---|---|---|---|---|---|
| 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.