How Starseal was built
This page tells the story behind Starseal: the problem it solves, the cloud pieces it runs on, the rules we set ourselves, and the choices we weighed along the way. It is written for anyone learning how to build software that handles other people's files with care. For the exact list of what the server can and cannot see, read Under the hood.
1. The problem
It started with an ordinary email. A set of group photos went to a mix of work and personal addresses, and most of it bounced: the attachments were larger than the receiving mail services allow. The work file-sharing tool could not help either, because it only shares inside the organisation.
The usual fix is to upload the files to a sharing service and send a link. That works, but the service can see every file. We wanted something that moves large files to anyone, with nothing to install, while the service in the middle never sees what it is carrying.
2. The big idea
Think of a locked box and a key. Starseal puts your files in the box inside your own browser, before anything leaves your computer. Only the locked box is uploaded. The key travels in the link you send.
The trick is where the key sits in the link: after the #. That part of a web address is called the fragment, and browsers never send it to servers. So the link looks like this:
/d/drop-id#key
The server sees the drop id and hands over the locked box. Only the person holding the whole link can unlock it, and they do that in their own browser too. This is called end-to-end encryption: the files are scrambled at one end and unscrambled at the other, and nothing in between can read them.
A fair question: if we publish exactly how Starseal works, doesn't that help an attacker? No. A good lock stays safe even when everyone knows how it is built, because the safety comes from the key, not from secrecy about the design. Cryptographers call this Kerckhoffs's principle, and it is why this page can exist.
3. The cloud pieces
Starseal runs on Cloudflare. Each piece has one job, and it helps to picture them as characters.
- The Worker is the doorman. A Worker is a small program that runs in Cloudflare's data centres. Every request passes through it. It checks that you are allowed in (the sender signs in; a recipient shows proof they hold the link), counts opens, and passes locked boxes in and out. It never holds a key, so it could not open a box even if it wanted to.
- R2 is the lockers. R2 is Cloudflare's file storage. It holds the scrambled pieces of each drop and nothing else. If someone stole the whole of R2, they would have a pile of noise.
- D1 is the notebook. D1 is a small database. It records each drop's id, sizes, expiry time and how many times it has been opened. It also keeps fingerprints of secrets instead of the secrets themselves: a fingerprint (a hash) lets the doorman check "does this person hold the right link?" without the notebook ever containing the link.
- The hourly cleaner is a scheduled job. Every hour it deletes drops that have expired, drops whose last allowed open has finished, and uploads that were abandoned half way. A week later it forgets the remaining notes about them.
4. The journey of a file
Sending
- The sender signs in with a passkey (more on that below) and chooses files, an expiry time and how many times the drop may be opened.
- The browser makes a fresh random key for this drop. From it, it derives several separate keys, each with one job: one to lock the files, one to draw the Seal, one to prove "I hold the link", and so on. Keeping jobs apart means a mistake in one place cannot unlock everything.
- Each file is cut into pieces of 1 MiB, and every piece is locked on its own with AES-256-GCM, the same kind of encryption your bank's website uses. Each piece is stamped with its position and a flag on the last one, so nobody can quietly reorder, drop or swap pieces: the unlocking step would notice.
- The locked pieces are uploaded in batches. If a batch fails, the browser tries again a few times before giving up and saying which file failed.
- When everything has arrived, the drop is sealed. The sender gets the link to share, a Seal to compare, and a private receipt link.
Opening
- The recipient opens the link. Their browser works out, from the key in the fragment, a proof that it holds the link, and shows that proof to the doorman. Only then does the server hand over the locked list of file names, which the browser unlocks and shows.
- Nothing has been counted yet. Chat apps often visit links to draw a preview, and we did not want a preview to use up someone's only open. An open is counted only when a person presses Break the seal.
- That press is counted in a single, all-or-nothing database step. If two people press at the same moment on the last allowed open, exactly one of them gets it.
- The browser downloads the locked pieces, unlocks them one by one and writes them straight to disk. A 2 GB file never has to fit in memory. Some browsers can write to a file directly; for the others, a small helper script inside the page (a service worker) turns the stream into an ordinary download.
- If any piece fails its check, the download stops and says so. A damaged file is never handed over as if it were fine.
- On a drop that can be opened only once, pressing "I have saved everything" deletes it straight away. Otherwise the hourly cleaner removes it when its time is up.
5. The rules we set ourselves
Assume the server will be breached one day
We designed as if an attacker could one day read everything Cloudflare stores for us. That single assumption decided a lot: keys never reach the server, secrets are stored only as fingerprints, and even optional names that recipients type are locked in their browser before they are sent.
Keep as little as possible, for as short a time as possible
Data you do not have cannot leak. Drops live for an hour, a day or a week at most. The notes about them are forgotten a week after that. Request logs that would include people's IP addresses are switched off.
Say only what is true
Security tools often promise more than they deliver. We tried hard not to. When the receipt says "opened", it means the locked files were fetched; the server cannot know whether they were unlocked. The Seal helps you spot a swapped or fake link, but it is not what detects tampering (the encryption does that). Names on the receipt are whatever people typed. The Under the hood page also lists what Starseal cannot protect against.
Use small, boring tools
Every line of code in a page that handles keys is something that could go wrong, so we kept the pages small. They are plain TypeScript with no framework, all encryption uses the browser's own built-in cryptography, fonts are served from Starseal itself, and the pages load nothing from any other website. A strict content security policy tells the browser to refuse anything else. Even the "Buy me a coffee" button is a plain link rather than an embedded widget, so that no outside code ever runs on a page that holds a key.
Treat the free tier as a design limit
Starseal runs within Cloudflare's free allowances, and we treated those allowances like the walls of a room. The code keeps its own count of storage and of uploads and downloads each month, and it politely refuses new work once it reaches about eight or nine tenths of an allowance, well before anything could turn into a bill. It also helps that Cloudflare does not charge for data sent out of R2 or for deleting files, so deleting early costs nothing.
6. Choices we weighed
| Question | What we chose, and why |
|---|---|
| Send directly between two browsers, or store and forward? | Direct transfer (peer to peer) never stores the file anywhere, which is lovely, but both people must be online at the same time. Store and forward lets the sender go to bed and the recipient open it tomorrow. We chose store and forward with end-to-end encryption, and may add a live mode later. |
| Passwords or passkeys for the sender? | Passkeys. A passkey lives on your device and is unlocked with your fingerprint or face. There is no password to reuse, guess or type into a fake site. Checking a passkey takes some computing time, and a free Worker gets very little per request, so we check the real timing on the live service and keep a simpler fallback ready in case it does not fit. |
| Accounts for recipients? | No. The link is the permission. Asking people to sign up just to collect some photos is exactly the friction we set out to remove. |
| One link for a group, or one link each? | One link, with an optional open limit and an optional name box. A link each would give stronger tracking, but it turns a simple email into a mail merge. The receipt shows each open, the name typed (if any) and whether everything was saved. |
| What if a link leaks? | Whoever holds the whole link holds the drop, so for sensitive files there is an optional spoken phrase: four random words sent another way, such as a phone call. Half the key is in the link and half comes from the words. The phrase is only ever checked online, and five wrong guesses delete the drop, so a stolen link alone is not enough. |
| How do two people know they have the same drop? | The Seal. Comparing long codes is tedious and error-prone; comparing a picture and three words over the phone is easy. The Seal is drawn from the drop's key and its exact list of files, so a different drop gives a visibly different Seal. |
| Why Matariki? | We wanted an image rooted in Aotearoa, and one that already means looking up together. The Seal shows the nine stars of Matariki at their real positions in the sky; the drop only turns the cluster, colours it and adds faint background stars, so the stars themselves are never distorted. We intend to ask a Māori cultural advisor to review the imagery and wording before Starseal is offered more widely. |
7. How we checked it
- Frozen test answers. We saved the exact output of the encryption for fixed inputs, and the tests fail if that output ever changes. Otherwise a harmless-looking code change could silently stop older links from opening.
- Tests for every part. The encryption, the Seal and the page logic have their own tests. The server code is tested against a local copy of Cloudflare's Workers, storage and database.
- A real browser test. An automated browser signs in with a test passkey, seals three files, opens them in a separate browser, and checks that every byte saved matches the original. It also tests a spoken-phrase drop and the receipt.
- Written design first, then review. Each feature began as a written design, then a step-by-step plan, and every change was reviewed before it was merged.
- A release checklist covers what automated tests cannot: saving on real phones, very large files, and watching the free-tier usage.
8. Lessons to take with you
- Decide what you are protecting, and from whom, before you write code. We call this a threat model.
- The safest data is data you never collect. The next safest is data you delete soon.
- Let the design be public and keep the keys private.
- Give each key one job.
- Count carefully: an action that must happen once needs a single all-or-nothing step.
- Write honest words on the screen. People make decisions based on them.
- Put hard limits in code rather than hoping usage stays small.
- Test the things that must never change, and test the whole journey in a real browser.