Protocol

naastenka/2

Invited devices, signed requests, and a server that cannot read anything it stores — and no longer sees the names on a board either. The full specification, with an OpenAPI file and test vectors, is in the repository under protocol-v2/.

Every installed app is a device. The first time it talks to a server it makes a P-256 key in the phone’s or Mac’s secure hardware — usable, never copyable — and every request it sends after that is signed with it. A board is two secrets: a 64-byte key that seals everything on it, and a P-521 key whose public half the server holds, so it can check that a request comes from somebody who has the board.

The assumption

Everybody on a board is friendly towards everybody else on it. A board is a kitchen noticeboard shared by people who already live together; the interesting adversary is the server and the network, not the flatmate. So inside a board there are no per-person signatures and no name ownership: a name is a label, and anybody on the board can write under anybody’s.

What version 2 adds is a wall around the board. The server keeps a list of which devices are on it and answers nobody else, and an invite no longer carries the key at all.

Notes, reactions and names

A note is {"k":"n", "name", "t", "a", "id"}, padded to a multiple of 256 bytes and sealed with ChaCha20-Poly1305. It is stored in a slot named HMAC(K_slot, "note:" + name) — so the server sees an opaque code, never the name, and a client checks that the name inside a note matches the slot it came from. Each person’s reactions are one more sealed blob in a slot of the same shape: the server cannot tell a reaction from a note, or which note it is about.

Invites

  1. The inviter’s app makes a 64-byte secret and registers a commitment to it. The link carries the secret, never the board’s key.
  2. The receiver’s app proves it has the link and leaves a one-off public key. The invite is used up.
  3. Both apps show four words derived from the link’s secret and the receiver’s keys. The two people compare them.
  4. The inviter confirms; their app seals the board to the receiver’s key. The server only ever relays sealed bytes.

Somebody who intercepts a link can use it up, but their words will not match and they are declined. A server that swaps in its own key cannot produce matching words, and could not open what was sealed if somebody confirmed anyway.

The wire

HTTPS and JSON. The apps come with two servers, api.naastenka.sideka.la (the default) and naastenka.www.cavoj.net. Binary is unpadded base64url. Every request carries Naastenka-Device, Naastenka-Nonce and Naastenka-Signature; requests about a board also carry Naastenka-Board-Signature. Anything about a board the caller may not see is the same 404.

Route
POST /v2/devicesRegister this device’s public key; the server answers with an id for it.
POST /v2/boardsAsk for a board. It works once somebody at the server approves it.
GET /v2/boards/<board>/approvedHas it been approved? Every wrong answer is the same false.
GET /v2/boards/<board>The sealed settings and every sealed slot, members only.
PUT /v2/boards/<board>/slots/<slot>Replace one slot — a note or somebody’s reactions; the server cannot tell which.
PUT /v2/boards/<board>/settingsReplace the board’s sealed name and reactions list.
POST /v2/boards/<board>/invitesOpen a one-time invite, good for a day.
POST /v2/invites/<invite>/redeemUse one. The receiver waits for the inviter to confirm.
POST /v2/invites/<invite>/acceptThe inviter confirms and hands over the board, sealed to the receiver’s device.
DELETE /v2/boards/<board>/membershipTake this device off a board. Nobody can take anybody else off.
GET /v2/invites/meInvites this device sent and received, while they are live.
DELETE /v2/invites/<invite>The inviter declines or withdraws it; the receiver, once it has the board, says “got it”.

Limits

A request’s nonce must be within five minutes of the server’s clock and is never accepted twice. Bodies are at most 16 KiB, a sealed note or settings blob at most 8 KiB, and a board holds at most 256 slots. Over a limit the answer is 429 with a Retry-After:

  • Registering a new device: 20 per IP address a day. Asking for a board: 5 per IP address a day.
  • Reading a board: 120 per device and board an hour. Writing a slot or the settings: 60 per device an hour. Everything a device signs: 3600 an hour.
  • Opening invites: 20 per device a day, and at most 10 live on one board at a time.
  • Redeeming: 30 tries per IP address an hour. Five wrong ones lock that device and that address out of redeeming for an hour — and never touch the invite, so nobody can spoil somebody else’s.

An open invite lasts a day; once confirmed, the receiver has a week to collect it. Boards that are never approved go after 30 days, and a board nobody is on any more is deleted.

What it is built out of

  • ECDSA P-256 for devices, P-521 for boards, ECDH P-521 for sealing an invite.
  • HKDF-SHA512 and HMAC-SHA512 for everything derived.
  • ChaCha20-Poly1305 for everything sealed, with a random 12-byte nonce.

All of it is in the platforms’ own libraries — CryptoKit, Android’s, Python’s cryptography. Nothing is hand-rolled.

The honest gaps. The server knows which devices are on which board and, while an invite is open, who invited whom. It can stay quiet about a note, and it can hand an old one to a device that never saw the newer. There is no un-inviting: removing somebody means a new board. And every elliptic curve here falls to a large enough quantum computer — the notes themselves do not.

Running your own

The repository has the OpenAPI file, a page of bullet points per endpoint saying what a server must do, and test vectors. It is worth being clear about why you would bother: not for privacy. Notes are sealed before they leave the device, so api.naastenka.sideka.la is exactly as unable to read your board as your own machine is. Run your own because you want the bytes on your disk.