Epochs
An epoch is one period of an album's membership, with one album master key (MK): 32 random bytes. Keys are generated independently, so one epoch's key says nothing about another's. Members keep every epoch key they receive, because a photo stays encrypted under the epoch it was uploaded in.
| Event | New epoch? | Why |
|---|---|---|
| Album created | Epoch 0 | The album needs its first key |
| Someone is invited | No | They receive the existing keys, so they can see the history, which is the point of joining |
| Someone is removed or leaves | Yes | Photos from now on must use a key they never had |
I chose to rotate only on removal because it is the one event where a new key protects anything. Rotating on every join would cost a handshake per member and hide nothing, since the newcomer receives all the old keys anyway.
One admin at a time
| Action | Admin | Member |
|---|---|---|
| Upload, and delete their own photos | Yes | Yes |
| Invite someone | Yes | No |
| Remove someone else | Yes | No |
| Vouch for a member's keys | Yes | No |
| Start a new epoch | Yes | Only while one is owed |
| Make someone else the admin | Yes | No |
| Leave | Yes, by handing the album to another member | Yes |
The app calls the admin the owner. Each album has exactly one at any moment: the creator at first, then whoever the admin hands the album to. The admin is the album's source of authority because only the admin signs the notes that say whose keys may make an epoch. Any member with such a note can make the new epoch after someone leaves, so an album never waits on one phone. The database has a co-admin role, but it is switched off. Several admins raise questions about who wins a conflict that I have not settled, so co-admins are still planned.
Creating an album
- Alice's phone creates Picnic on the server with a placeholder title, because no key exists yet to encrypt the real one.
- It generates MK0.
- It fetches its own prekey bundle and runs the normal handshake with itself, producing a wrap addressed to its own member token.
- It signs that wrap, the epoch change, and a member note for itself at term 0, and sends epoch 0.
- Once the server accepts it, the phone installs MK0, encrypts the real title under it and replaces the placeholder.
Wrapping the first key to yourself is not a backup: a reinstalled app has new keys and cannot open it. It exists so that epoch 0 has exactly the same shape as every later epoch, and the server checks it the same way.
Member notes
Before a member can make a new album key, the other phones need to know that the member's keys really belong to them and were not picked by the server. The admin vouches for each member with a signed note:
note_sig = Ed25519(IK_admin, "member-note-v1" || album_id (16) || member_token (32)
|| u32_be(generation) || IK_member (32) || LK_member (32)
|| u32_be(issuer_term) || 0x01)generationcounts how many times this member token has joined. Someone removed and invited back gets the next generation, so a note from their earlier membership no longer counts.issuer_termis the admin term the signer held, explained under Handing an album over.0x01is the only permission: starting an epoch while this membership is active. A note never lets anyone invite, remove or vouch for others.- The creator signs their own note at term 0 and sends it with epoch 0. Every invite carries the newcomer's note, plus a fresh note from the inviting admin for each current member who lacks one from them. The keys in those fresh notes are copied from notes the admin's phone already verified, never from the member list the server shows.
- The server checks each note's signature, and that its keys are the ones that account publishes.
- Notes are kept apart from the membership rows, until the album is deleted. A key delivery signed by someone who later left or deleted their account can still be verified by a member who joins afterwards.
A note is not the Verified badge. A note means the admin vouched for a key; Verified means you compared safety numbers yourself.
Signed epoch changes
To start epoch N, a member's phone makes a fresh MK, runs one handshake per remaining member, and sends every wrap in one request, with a signature over the whole change:
member_set_hash = SHA256(u32_be(count) || member tokens, sorted)
wraps_hash = SHA256(u32_be(count) || for each wrap, sorted by token:
token (32) || ek_pub (32) || u32_be(opk_index or 0xFFFFFFFF)
|| u32_be(len) || wrap || u32_be(len) || sender_sig)
envelope_sig = Ed25519(IK_signer, "epoch-set-v1" || album_id (16)
|| u32_be(N) || member_set_hash || wraps_hash)The server takes a lock on the album row, then checks:
- the caller is an active member and holds a note for their current generation,
- a caller who is not the admin is settling an owed epoch, because members only start an epoch after someone leaves,
- N is exactly the current epoch plus one,
- the tokens are exactly the active members, with no duplicates,
- both hashes match the request, and
envelope_sigverifies under the caller's IK.
Only then does it store the epoch and every wrap in one transaction and notify members, who each fetch their own wrap. Removals, epoch changes, invites, handovers and uploads all take the same album lock, so none of them can interleave.
The phone making the change wraps the new key only to keys it found in notes signed by an admin it trusts. If any active member has no note it can verify, it stops before a key is even generated. Phones receiving the change check the signer the same way, through the signer check.
Two members can try at once. Both propose the same N, the album lock makes them run one after the other, and the second fails the "current plus one" check. The losing phone installs the winner's key before its own uploads resume. Phones other than the admin's wait a random half second to three seconds before trying, so several phones opening together rarely spend each other's one-time prekeys on a race only one can win.
Two parties can never start the epoch: the person who left, because the server refuses their requests, and the server, because it never holds an album key.
Why sign the whole set rather than just each wrap: a per wrap signature proves who sent one key, but not who else got it. Signing the member list and every wrap together means a server cannot quietly add a recipient, drop one, or swap a wrap without breaking the signature.
Inviting with history
Bob shares his Miuchio ID with Alice. Picnic is at epoch 0.
- Alice's phone fetches and checks Bob's prekey bundle.
- It runs one handshake with Bob.
- It wraps every MK it holds, from epoch 0 to the current one, under that single secret. Each wrap has a fresh nonce, its own epoch in the associated data and its own signature.
- It picks a random member token for Bob and signs his note with the keys from his bundle, plus fresh notes for current members who need one.
- The server, under the album lock, checks that Alice is still the admin, neither account is being deleted, the wraps cover exactly epochs 0 to current, no new epoch is owed, the album has fewer than 10 members, and every note verifies. Then it adds Bob and stores his note, the other notes and the wraps in one transaction, so no member is ever left without a note.
- Bob's phone takes Alice as its anchor, the admin it trusts at her term, but only because it holds no keys for Picnic yet, and only after her signature on his wraps verifies. It installs every epoch from 0 upward and sends a signed receipt:
Ed25519(IK_Bob, "join-complete-v1" || album_id || u32_be(epoch) || ek_pub). The server accepts it only ifek_pubmatches the wraps of Bob's current membership, so a late receipt from an earlier membership cannot count, and records the newest epoch Bob has confirmed.
One handshake for the whole history is deliberate. The invitation grants all of it anyway, so separate handshakes would protect nothing extra, and one handshake uses only one of Bob's one-time prekeys.
If Carol is removed and later invited back, she gets her old member token again, because signed history already refers to it. The server refuses Alice's first attempt and answers with that token and Carol's next generation, before anything is stored. If Alice's phone pinned a key for Carol before and the new bundle shows a different one, it stops there: an account can never change its identity key, so a different key means the bundle was substituted. The check runs after the first request, so it does not stop a malicious server, as Trust and verification explains. Otherwise it signs a new note and sends the same wraps again, without spending another one-time prekey. Carol rejoins as a plain member, her old wraps are replaced, and her old encrypted name is dropped because it was sealed under a key she may no longer hold.
Removing someone
Alice removes Carol. The order is always revoke, then rotate.
- In one locked transaction the server marks Carol revoked and sets the album's
rotation_requiredflag. Carol loses access to every album request at once. Photo download links she was handed before that keep working until they expire, at most 30 minutes later, and they only reach photos she could already open. - From that moment uploads to Picnic are refused. An upload already in progress is refused when it tries to confirm.
- The first remaining phone to notice, Alice's or Bob's, creates epoch 1 for Alice and Bob, wrapping only to keys in notes it has verified.
- Committing epoch 1 clears the flag, and uploads continue under MK1.
The freeze is the important part. Between steps 1 and 3 the album's current key is still MK0, which Carol holds. Without the freeze, a photo Bob uploads in that gap would be encrypted under a key Carol has. The gap usually lasts seconds. Nobody can upload while their phone is offline, and the first remaining phone to come online makes the new key before its own photos go up.
Why the flag is stored instead of computed: an earlier version compared the current epoch's recipients with the active members. When a departed account is deleted, its wraps are deleted too, the two lists match again, and the album looks settled while that person still holds the current key. A safety rule inferred from data can be undone by an unrelated feature that deletes data. The comparison is still checked as well, but it can no longer switch the freeze off. The full story is in Removing someone without leaking the next photo.
Leaving works the same way, except Carol revokes herself and her phone deletes its copy of the album. A remaining phone still has to create the next epoch. Each one tries on launch, on reconnect, when it hears about a removal, and when one of its own uploads is refused for this reason.
Handing an album over
Alice can make Bob the admin straight away, with no accept step, and either stay as a plain member or leave in the same step. It is the only way an admin can leave without deleting the album. Handing over alone makes no new key, because nobody lost access. Leaving does, as with any departure.
handover_sig = Ed25519(IK_old_admin, "admin-handover-v1" || album_id (16)
|| u32_be(term) || prev_hash (32) || old_token (32)
|| new_token (32) || u32_be(new_generation)
|| IK_new (32) || LK_new (32)
|| mode (1 stay, 2 leave) || delete_my_photos (1))
prev_hash = SHA256(previous record's signed bytes || its signature)
32 zero bytes for the first handover- Terms count handovers. The creator holds term 0 and each handover adds one. They are separate from epochs because a handover makes no new key.
- Alice's phone takes Bob's keys from the note it already verified for him, never from the member list.
- Under the album lock the server checks that Alice is the admin, the term is the next one, and the signature and
prev_hashmatch the stored chain. Bob must be another active member whose phone has confirmed receiving the album keys, with a note, and an account that is not being deleted or suspended. The server then stores the record, swaps the two roles and, if Alice is leaving, revokes her in the same transaction, applies her choice about her photos and marks a new epoch as owed. - Each phone starts from its anchor and walks the records forward, checking each one with the previous admin's key. That gives it every admin key it trusts, by term, and it accepts a note only if one of those keys signed it. A phone never trusts terms before its anchor, which is why an invite carries fresh notes from the inviting admin.
- A record that does not chain onto the history a phone already accepted is refused, so the server cannot swap one handover for another.
Before sending, Alice's phone saves the exact signed request. If the answer is lost, it asks the server by a private operation id whether the handover committed, and only then wipes the album or refreshes her role. If Alice stayed, sending the identical request again returns the first result. If she left, the server refuses her album requests, so her phone finds the result by the operation id instead. The operation id is not part of the signed record, so other members never see it.
Catching up after being offline
Realtime events are only hints; a phone that was asleep misses them. On launch and reconnect the app asks for each album's current epoch, compares it with the keys it holds, and installs every missing epoch oldest first. It does the same when a photo cannot be opened because its album key has not arrived, trying a few more times over the next couple of minutes. Work for one album runs in order, so keys never install out of sequence.
If an epoch cannot be installed, the album is marked blocked with one of these reasons:
- the signer's identity key does not match the one pinned for them,
- the signer is unknown on an album this phone already has keys for,
- this phone's own member token carries someone else's identity key,
- the wrap is still missing after retries,
- the signature or decryption failed,
- the one-time prekey the wrap names is no longer on this phone,
- the key conflicts with one already installed.
Deleting an account
| Situation | What happens to the album |
|---|---|
| You are the only member | It is deleted |
| You are the admin and others remain | It is deleted for everyone, after you confirm each one. To keep it, hand it to another member first |
| You are a member | You leave, your photos are deleted, and a new epoch is owed |
The server accepts the request, ends every session, and a background job removes the account one album at a time, each step its own transaction so a crash resumes where it stopped. The phone sends a random receipt with the request and keeps it in a small file. If the response is lost, the phone asks whether that receipt was accepted before wiping itself, so it never wipes for a deletion that did not happen.
Someone who removed the app or lost their phone can delete their account from the website instead. They enter their email and receive a code that only deletes the account and never signs them in. A correct code returns a ticket that lasts ten minutes and can be used once, along with counts of what will be deleted. The browser never sees album names or IDs.
Confirming hands the same background job the same plan the phone would send. If the answer to the confirmation is lost, the page asks the server to settle it. That request and the deletion compete for the same receipt row as the app's Keep my account, so the answer it gets back cannot change afterwards.