Starseal

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.

Your browser talks to the Worker, which stores scrambled bytes in R2 and small records in D1. An hourly cleaner deletes what has expired from both. Your browser locks and unlocks every file scrambled bytes only Cloudflare Worker the doorman: checks tickets, holds no keys R2 storage lockers holding scrambled bytes D1 database notebook of ids, times and fingerprints Hourly cleaner deletes whatever has expired

4. The journey of a file

Sending

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. If any piece fails its check, the download stops and says so. A damaged file is never handed over as if it were fine.
  6. 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

QuestionWhat 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

8. Lessons to take with you

  1. Decide what you are protecting, and from whom, before you write code. We call this a threat model.
  2. The safest data is data you never collect. The next safest is data you delete soon.
  3. Let the design be public and keep the keys private.
  4. Give each key one job.
  5. Count carefully: an action that must happen once needs a single all-or-nothing step.
  6. Write honest words on the screen. People make decisions based on them.
  7. Put hard limits in code rather than hoping usage stays small.
  8. Test the things that must never change, and test the whole journey in a real browser.
Buy me a coffee