kokkoja-rel/docs/implementation.md

How Kokkoja works

This part is for the curious, for anyone who wants to run a Kokkoja server, and for anyone who wants to read or change the code. It describes the parts, what travels between them, what is protected and what is not, and how pages are stored. The code is the final word; it is short and commented.

The parts

Kokkoja is three programs and a few static files.

• The client (client/) runs in the web browser and does everything the user sees: the pen, the page, the text, the encryption, the saving. It is plain JavaScript modules, run by the browser as written, with no build step and no third-party packages. Its types are written in JSDoc comments and checked by the TypeScript compiler during development.
• The local program (kokkoja.py) runs on the user's computer. It serves the client to the browser at http://localhost:8760/, keeps the user's identity, and reads and writes the notebook directories, which a web page cannot do on its own. It uses nothing but Python's standard library.
• The relay (relay/kokkoja_relay.py) runs on a server that every participant can reach. It passes messages between the members of a session and nothing more: it cannot read them and it stores nothing. It is Python with one library, websockets.
• The web site is the client/ directory served over HTTPS, with a config.json beside it, so that a guest can join without the local program. deploy/ has the server setup.

Every participant's computer holds the whole page. Only changes travel: a stroke as it is drawn, a text block as it is typed, an erasure, a new page, an image once. There is no central copy.

Why the relay exists

Two computers behind home routers generally cannot connect to each other directly, so something in between has to pass the messages. The relay is the smallest such thing: a WebSocket server with rooms. A client connects to wss://<server>/relay/room/<room id>; the relay gives the connection a number, tells the room that a peer has arrived, and from then on sends every message it receives from one member to all the others, stamped with the sender's number. When the last member leaves, the room is gone. It holds at most 32 members per room and 500 rooms, and refuses messages over 1 MB; clients split anything larger.

Sessions and encryption

The invitation is

<relay address>#<secret>.<host id>

The secret is 16 random bytes, made by the host's browser. From it every client derives two values with HKDF-SHA-256: the room id, which names the room at the relay, and the message key, a 256-bit AES-GCM key with which every message is encrypted before it is sent and decrypted on arrival. The relay sees the room id, the members' network addresses, and the size and timing of encrypted messages. It cannot compute the key from the room id, so it cannot read anything. Neither can anyone watching the network between the participants and the relay, which is TLS-protected in any case.

A link invitation wraps the same text:

https://<site>/#join=<invitation>

Browsers never send the part of an address after # to the site, so the secret stays between the host and the guests.

Identity and layers

Each participant has a signing key pair (ECDSA on P-256), made in the browser the first time and then kept, by the local program in its configuration directory or by the browser in its own storage. The participant id is the first 16 bytes of the SHA-256 hash of the public key. When a client joins a room it announces itself with a signed hello carrying its name and public key; the signature covers the room id and the peer number the relay stamped on the message, so nobody can replay it elsewhere or claim another peer's connection. Until a peer has sent a valid hello, everything else from it is ignored.

A page is a stack of layers, one per participant, keyed by participant id. A client accepts a change to a layer only from the participant whose id it is, so the rule "nobody can change anyone else's writing" is not a permission that could be misconfigured but a consequence of how the data is organised. Because the id is derived from the key, and the key is kept, a person is the same participant in every session from the same computer, and their writing on a page loaded weeks later is still theirs.

The host is whoever holds the key whose id is in the invitation. Pages, images and the list of guests allowed to start pages are accepted only from the host (or from an allowed guest, for pages and images).

Pages

Page coordinates are in units of 0.1 mm. A blank page is an A4 sheet, 2100 by 2970 units. Writing within 8 mm of an edge grows the sheet by 8 mm on that side. An image is placed at its natural size, taken from the resolution recorded in the file, or 0.1 mm per pixel when there is none, centred across the sheet, 8 mm from the top or from the image above, scaled down if wider than the sheet inside its margins (or, if the person adding it chooses, placed at natural size with the sheet widened to hold it). A page holds at most 12 images and 24 MB of image data. An image file over 2400 pixels on a side or 1.5 MB, or not PNG or JPEG, is redrawn at most 2400 pixels and stored as JPEG before it is shared; smaller PNG and JPEG files are shared byte for byte.

A stroke is a list of points with pressure, and the line width is a function of pressure: nominal at a pressure of 0.4, about 2.6 times that at 0.75. Points are sent while the stroke is drawn, so the others see it grow. A text block is sent whole at every keystroke, with its line breaks already laid out by the writer's browser, so that everyone shows the same lines.

Each page has a number, counted from 1 in the session, and a random id. A client that joins late asks the longest-connected member for the layers of absent participants, and receives each present participant's layer from that participant. A client that reconnects after a dropped connection sends its whole layer again, so that nothing drawn meanwhile is lost.

The page file

A notebook is a directory. The page being written is Current.svg in it, rewritten a moment after every change (at most every 400 ms while writing continues, at least every 2 s). A kept page is a copy of Current.svg named YYYY_MM_DD_NN.svg, the day being when the page was last changed and NN a serial number within that day. A copy is made when the user asks (Keep page), and by the program whenever Current.svg is about to be given to another page: when the session moves to a new page, when the notebook is changed, and when a session begins and finds a page of another session in the notebook. Nothing is copied if the page is blank or an identical copy already exists.

The file is an SVG document that any viewer displays: the images as embedded <image> elements, each layer as a group with the participant's name and id, each stroke as a path and each text block as text. Beside the shapes, the same elements carry Kokkoja's own data in attributes, the exact points and pressures, the text and its breaks, so that Kokkoja reads the page back without loss, with each layer still belonging to its participant. The session id and host id are recorded too, which is how a reloaded tab knows that Current.svg is its own page to continue from.

With the local program, the notebooks are in Kokkoja in the Documents directory (--notebooks chooses another place), the identity and the browser's token in the configuration directory (~/.config/kokkoja on Linux, ~/Library/Application Support/kokkoja on macOS). In the browser, the notebooks are in the site's IndexedDB under the same names and rules, and the identity in its localStorage; a kept page and an exported picture are offered as downloads, since that is the only way a web page can hand a file to its user.

The local program and its token

The local program listens on 127.0.0.1 only. Any web page open in the browser could nevertheless send requests to localhost:8760, so every request that touches files must carry a secret token, which the program makes once, keeps in its configuration directory, and passes to the browser in the address it opens (#token=..., which the browser keeps in its local storage and never sends to any server). Requests without the token are refused. The program also checks that requests come from its own origin. Outside the notebooks it reads only image files and writes only PNG files, each where the file chooser was pointed.

The web site, and whom you trust

A client served by a web site is a web application like any other: the site operator's code runs in your browser. The end-to-end encryption protects the session from the relay and the network, but a dishonest site could serve a client that gives the key away. Participants who run the local program load the client from their own disk and are not exposed to that; they trust the code they downloaded once. The site sends a Content Security Policy that lets the client load nothing from anywhere else, which protects against the ordinary web attacks but not against the operator. For a lesson this is the same trust one places in any video call service, and considerably less than in one that sees the content; it is stated here so that nobody is surprised.

Running a server

A server is a machine with a public name, TLS and nginx (or any reverse proxy that passes WebSockets). deploy/README.md describes the one Kokkoja comes with: the relay as a systemd service bound to localhost, nginx terminating TLS, serving the client's files at https://<name>/ and forwarding wss://<name>/relay/ to the relay, and a config.json telling the client which relay to use and that notebooks are kept in the browser. A host uses the server with

python3 kokkoja.py --relay wss://<name>/relay

and invitations become links to https://<name>/. One server serves any number of hosts and sessions at once; the relay's work per session is passing a few kilobytes per second. Since the relay cannot read what it passes, a server run by someone else is a matter of availability, not of privacy; the web site is the part that requires trust, as described above. A teacher who wants no dependence on anyone's server needs a machine of their own that is reachable from the Internet, which a computer behind a home router is not without arrangement.

What is not protected yet

• Only hello is signed. A participant working together with a dishonest relay could forge another participant's strokes. Signing every message, or page descriptors with the host's key, would close this.
• A participant can announce a page with a higher number than the host's, and the others move to it.
• The relay sees who talks to whom, when, and how much.

Pen input

The client uses the browser's pointer events, which deliver every sample a pen produces, with pressure, in Firefox and in Chromium-based browsers on Linux and macOS. The panel's last line shows what arrives. When a pen has been used, touches are ignored, so a hand resting on a touch screen does not draw; this rule has not yet been tested with a device that has both a pen and a touch sensor. Kokkoja opens none of the browser's system dialogs (the colour palette and, with the local program, the file chooser are its own), because one such dialog crashed Firefox on Linux.

Development

The code is Python and JavaScript only. The tests run with

.venv/bin/python -m unittest discover tests -v

where tests/test_end_to_end.py drives a headless Firefox through geckodriver with several participants, with and without the local program, and npm run check type-checks the client (the TypeScript compiler is the only development dependency). The relay's --host and --port and the local program's options are listed by --help.