How a shared list works with no server

We Need Bananas has no accounts and no database. Here's how your list gets from your kitchen to the person at the shop.

The three words are the list

When you start a list you get three random words, like lemon.fork.bulb, picked from about 1,600 everyday words. That's around four billion possible lists. The words are the list's name, its address (weneedbananas.com/lemon.fork.bulb) and its key.

On your device the words are stretched into a secret key (PBKDF2 with 600,000 rounds). That key produces a scrambled room id, which lets devices with the same list find each other, and a password that encrypts the connection handshake.

Every device keeps the whole list

Your list is saved in your browser's own storage. You can close the tab, lose signal or put your phone in airplane mode and it's still there. The site works offline once you've opened it.

Devices sync directly with each other

When two devices have the same list open, they connect peer-to-peer over WebRTC, the same technology used for video calls in the browser, and swap changes directly. To find each other they use free public Nostr relays, which only ever see the scrambled room id and an encrypted handshake. Your items go straight from device to device.

The list is a CRDT (we use Yjs). That means two people can edit offline at the same time and their changes merge cleanly when they reconnect. Nobody's edits get lost.

Step by step

Here's everything that happens between two phones, from typing in the words to an item showing up.

Your phonefull copy of the listNostr relayspublic · for introductions onlyTheir phonefull copy of the listrelays drop out1Pairing: meet up without ever sending the wordslemon.fork.bulbPBKDF2 · SHA-256600,000 roundsroom idpasswordlemon.fork.bulbPBKDF2 · SHA-256600,000 roundsroom idpasswordsame words in,same room id + password outjoin room 3f9a…join room 3f9a…connection offersealed with passwordconnection answersealed with passworddirect WebRTC data channelencrypted, phone to phone2Catch up: each phone asks for exactly what it's missingsv here's everything I've already gotupd the changes you don't have yetsv here's everything I've already gotupd the changes you don't have yetpres my name, and whether I'm at the shopBoth directions run at once. Offline edits from either side merge; nothing is overwritten.3Live: every edit goes straight acrossadd “bananas x6”upd just that one changeshows up for themsaved in IndexedDBsaved in IndexedDBtab reopened orback onlinesv anything I missed while asleep?upd here you go
Dashed grey lines go through the public relays and carry only the scrambled room id and a sealed handshake. Solid green lines travel over the direct phone-to-phone channel. Separately, each phone leaves an encrypted copy of the list on the relays for phones that open it later (see below).

Who sees what

Your phones

SeesThe three words, every item and who is on the list.

KeepsThe whole list, saved in the browser, so it works offline.

Nostr relays

SeesA scrambled 64-character room id, an encrypted handshake, and an encrypted copy of the list kept for phones that open it later.

Never seesThe three words, or any item on the list in readable form.

STUN servers

SeesIP addresses, so phones behind home routers can reach each other, as in any browser video call.

Never seesThe room id or any item on the list.

Our web host

SeesRequests for the app files, like any website, in short-lived logs. After your first visit, lists load from your phone.

Never seesYour items. There are no accounts and no database of lists.

When nobody else has the list open

You don't have to wait for the other person. Each phone also leaves a sealed copy of the list on a few public Nostr relays. It's encrypted with a key made from the three words (AES-GCM), and signed with another, so the relays can't read it and nobody without the words can replace it. Each relay keeps only the newest copy.

When a phone opens the list it picks up that copy and merges it in, then leaves a fresh one if it has anything new. So you can add your items, put your phone down, and whoever opens the list next still gets them. The badge at the top of the list says Up to date once your changes are waiting for them, or Live while you're connected to someone directly.

Each copy is marked to expire 30 days after the list was last opened or changed, and the relays delete it then. A list someone is still using is refreshed every time it's opened, so it never runs out. The relays are run by volunteers and don't promise to keep anything, so the copy on each phone is always the real list. The relay copy is just how changes get between phones that aren't open at the same time.

Built for shopping

  • Items sort into aisle order automatically, and you can reorder the aisles to match your shop.
  • Quantities are understood: "2 pints milk", "500g mince", "bananas x6". Duplicates merge.
  • Shop mode keeps your screen awake with big tick targets and a count of what's left.
  • "Couldn't find it" keeps an item for next time. "Done shopping" clears what you bought.
  • Things you buy often come back as one-tap usuals.

Start a list