ZEKORO / how it works zekoro.one This file is public on purpose. An encrypted messenger asks you to trust it, and "trust us" is worth less than a description you can check. So here is what the server can see, what it cannot, and where the sharp edges are. See also: changes.txt (what changed and when) and qna.txt (answers to the questions from the last security review). ──────────────────────────────────────────────────────────────────────── WHAT THE SERVER CAN NEVER READ ──────────────────────────────────────────────────────────────────────── Your keypair is generated in your browser when you sign up. The secret half is encrypted before it is ever sent, using a key derived from your password: PBKDF2(password, random 16-byte salt, 600,000 iterations, SHA-256) -> AES-256-GCM 600,000 is OWASP's current figure for PBKDF2-SHA-256. Accounts created before this used 210,000; their key blob is re-wrapped at 600,000 automatically the next time the password is typed (login or unlock). The server stores the iteration count next to each blob so the browser knows which to use. The server stores the encrypted blob and the salt. It never receives the unwrapped key and cannot derive it. Messages are sealed with nacl.box (X25519 + XSalsa20-Poly1305) between your secret key and the recipient's public key. The server stores ciphertext and a nonce. It knows who sent a message to whom and when. It does not know what it says. Images are encrypted once with a random key (secretbox) and uploaded as an opaque blob. The message itself carries only the blob id and the key needed to open it, sealed to the recipient like any other message. So: the server sees your username, your contacts, group membership, message timing and sizes, and (if you verify one) your email address. Not content. ──────────────────────────────────────────────────────────────────────── YOUR PASSWORD NEVER LEAVES YOUR DEVICE ──────────────────────────────────────────────────────────────────────── Logging in has to prove something to the server, but the password is also what unwraps your private key, so the server must not be handed it. What the browser sends instead is an auth key: authKey = PBKDF2(password, "zekoro-auth|" + authSalt, 600,000, SHA-256) authSalt is random per account and is not the salt that wraps your key, so the auth key and the key-wrapping key are unrelated values. The server stores scrypt(authKey) and compares against that. Knowing the auth key does not open your key blob. Login is two requests: /prelogin returns your auth salt (unknown usernames get a stable fake one, so it doesn't reveal which accounts exist), then /login sends the auth key. Accounts made before this scheme still sent the raw password. They log in the old way once, and the browser immediately moves the account over (new auth salt, auth key, re-wrapped key blob). From then on the password stays home. The same applies to password change and reset: only derived values are sent. ──────────────────────────────────────────────────────────────────────── PASSKEYS ──────────────────────────────────────────────────────────────────────── You can add passkeys in Settings > Security and sign in with one instead of your password. They're standard WebAuthn passkeys, held by whatever passkey manager your device uses, and require the device's own unlock every time. The server stores each passkey's public key and checks a fresh signature on every sign-in. Signing in isn't the same as unlocking: your messages need your private key. So when the passkey manager supports the PRF extension, the passkey also produces a secret that only it can make: PRF(passkey, "zekoro-passkey-prf-v1") -> HKDF-SHA-256 -> AES-256-GCM over your private key That sealed copy is stored with the passkey. The PRF secret never leaves your device (the app strips it before sending anything), so we can't open the copy. After sign-in your browser opens it and you're straight in, no password. On a device without PRF support the passkey still signs you in, and you type your password once to unlock; if that passkey can produce the secret, it's set up to unlock from then on. A password reset that makes a new keypair removes every passkey, since their sealed copies are of the old key and a reset shouldn't leave old sign-ins working. ──────────────────────────────────────────────────────────────────────── KNOWING YOU'RE TALKING TO THE RIGHT KEY ──────────────────────────────────────────────────────────────────────── The server is what hands out public keys. On its own, nothing would stop it (or someone who took over an account through a reset) from quietly swapping one for a key they control and reading along. Two things close that: Key pinning. Your device remembers the first key it sees for each person (trust on first use). If that key ever changes, the chat shows a red banner, the lock badge turns to "Key changed", and direct messages and calls stop going out until you look at it and accept. In servers, a member whose key changed gets a warning marker and a one-time notice, and your messages stop being encrypted to them until you accept their new key, so a hijacked account doesn't quietly keep receiving the channel. Safety numbers. Every pair of people has a 60-digit number built from both public keys (an iterated SHA-512 over each person's permanent account number + key, Signal style: 30 digits each, sorted, joined). Both screens show the same number. Read it out in person or over a call; if it matches, nobody is in the middle. Tap the lock badge in a chat, or "Verify safety number" on a profile, then mark it verified. Settings shows your own half as "Your key fingerprint". A key changes legitimately when someone resets their password without a recovery code (they get a fresh keypair). That is exactly what a hijacked reset looks like too, which is why it is loud instead of silent. Pins and verified marks live in your browser's storage on that device. A new device or a cleared browser starts fresh and trusts on first use again. ──────────────────────────────────────────────────────────────────────── CALLS ──────────────────────────────────────────────────────────────────────── Voice and video are WebRTC, media encrypted with DTLS-SRTP, peer to peer when the network allows, otherwise through our TURN relay (coturn), which forwards encrypted packets it cannot read. DTLS-SRTP is only as good as the fingerprints exchanged in the call setup (SDP). Those go through our server, so the SDP offer and answer are sealed with nacl.box to the other person's pinned key. The server forwards an opaque blob. A call setup that arrives unsealed, fails to decrypt, or comes from someone whose key changed is refused. ICE candidates (network addresses) are not sealed. The server and relay can see the IP addresses involved in a call, and on a direct connection so can the other person. Settings has "Hide my IP address in calls": with it on, your device only offers relay addresses, never contacts Google's STUN server, and the other side only ever sees the relay. It applies to calls and voice channels, and costs a little latency. The relay is turn.zekoro.one. It has to be reachable directly (Cloudflare can't carry TURN traffic), which means that name points at our server's real address. So the site itself only answers connections that come from Cloudflare; going to that address directly gets refused. The relay is locked down: it won't forward to private, loopback, link-local or reserved addresses (IPv4 or IPv6), won't open TCP connections at all, and a firewall rule stops it reaching anything on this machine except its own relay ports. Credentials last 12 hours and are minted per account. It keeps no logs. ──────────────────────────────────────────────────────────────────────── MESSAGES CARRY THEIR OWN CONTEXT ──────────────────────────────────────────────────────────────────────── nacl.box proves who sealed a message, but on its own it doesn't say where the message belongs. So everything is sealed inside an envelope: { where it belongs, a random message id, the sender's clock, payload } "Where" is "dm:>" for a direct message or "ch:::" for a channel, using permanent account numbers. On opening, your device checks all of it against where the server says the message is: - wrong place (a DM moved into a channel, or between chats): not shown - a message id already seen in that chat (a replay): not shown - sender's clock more than 10 minutes off the server's timestamp: shown with a warning that it may have been replayed Messages from before the envelope existed are still shown; anything newer that arrives without one is refused. ──────────────────────────────────────────────────────────────────────── SERVERS (GROUPS) ──────────────────────────────────────────────────────────────────────── There is no shared group key. A message in a channel is encrypted separately to every member who can see that channel, and stored once per recipient. Who can see it is worked out by the server from the permissions below, fetched fresh on every send, and the server refuses any copy addressed to someone who can't. So a private channel's messages are never even encrypted to people outside it. When someone leaves, is removed, or loses access to a channel: - new messages are not encrypted to them, so there is nothing for them to decrypt, and the server refuses their reads of the channel anyway - messages they already received stay readable to them, as they would in any messenger; that can't be un-sent The cost of fan-out is size: a message in a 50-person server is 50 ciphertexts. Fine at this scale, and it keeps removal simple and immediate. ──────────────────────────────────────────────────────────────────────── ROLES AND PERMISSIONS ──────────────────────────────────────────────────────────────────────── Modelled on Discord, enforced on the server for every request: View channels Send messages Connect to voice Create invite Manage messages Manage channels Manage roles Kick members Manage server Administrator (everything) What a member can do = @everyone's permissions + their role's, then the channel's overrides on top (@everyone override first, then their role's; a deny beats an allow at the same level). New servers give @everyone: view, send, connect to voice, create invite. The owner can do everything and can't be kicked, re-roled or overruled. Deleting the server is owner-only. There are no role positions. Instead: you can only hand out, take away, or act on permissions you hold yourself. A moderator can't make an admin role, can't give themselves one, can't edit or delete a role that has something they lack, and can't kick or re-role someone who outranks them. Permissions decide who can see and post. They are not encryption: the server enforces them, so a malicious server could ignore them. What it still can't do is read what was said, because every copy is sealed to its reader. ──────────────────────────────────────────────────────────────────────── VOICE CHANNELS ──────────────────────────────────────────────────────────────────────── A voice channel is a mesh: everyone in it holds a direct WebRTC connection to everyone else, audio only, DTLS-SRTP encrypted, through the TURN relay when a direct path isn't possible. Audio never touches our server. The server only keeps a list of who is in which room and passes setup messages between people in the same room. The setup (SDP) is sealed to each person's pinned key exactly like 1:1 calls, so the server can't wedge itself into the audio either. Someone whose key changed is refused until you accept it. A mesh means every person uploads one copy of their voice per listener, so rooms cap at 8. That's the honest limit of doing it without a media server, and a media server would have to be trusted with the audio. Joining needs View channels + Connect to voice on that channel. Being kicked from the server, or the channel being deleted, drops you from the room. ──────────────────────────────────────────────────────────────────────── INVITES ──────────────────────────────────────────────────────────────────────── Two kinds, both at zekoro.one/s/: one optional custom link per server (Manage server), and any number of generated codes (Create invite) that can expire after 30 minutes to 7 days and/or stop after N uses. Anyone holding a live link can preview the server and join it. ──────────────────────────────────────────────────────────────────────── THE PART PEOPLE GET BURNED BY ──────────────────────────────────────────────────────────────────────── Your password is the only thing that unwraps your private key. That is the whole point, and it has a consequence nobody likes: Forgetting your password without a recovery code means your old messages are gone. Not "gone from your view". Mathematically unreadable, by you, by us, by anyone. A password reset proves you own the account and gets the account back. It cannot get the messages back, because there is nothing to decrypt them with. The fix is the recovery code in Settings. It is 16 random characters from a 32-symbol alphabet (80 bits), generated in your browser and shown once. It wraps a second copy of your private key: PBKDF2(code, random salt, 210,000 iterations, SHA-256) -> AES-256-GCM We store that copy; it is inert without the code, which we never receive. The code is random rather than chosen by a human, so 80 bits is already far out of brute-force reach and the iteration count matters much less than it does for a password. Keep the code somewhere that is not your account. Three ways your password can change, and what each costs: Change password (you know the current one) -> nothing lost Reset + recovery code -> nothing lost Reset, no recovery code -> account back, history gone, contacts see "key changed" We will not "fix" the third case by keeping a copy of your key. A system where the operator can restore your messages is a system where the operator can read them. ──────────────────────────────────────────────────────────────────────── PASSWORD RESETS ──────────────────────────────────────────────────────────────────────── Request a reset and a six-digit code is issued. If you have a verified email, it goes there. If you don't, it is delivered as an encrypted DM to the owner account (@fede), who passes it to you directly. That DM is sealed like any other message, by an automated account called RSTPSW that only ever sends. That makes @fede a trust point for accounts with no email: whoever holds the code can take the account. What they cannot take is your history (no recovery code, no old key), and your contacts get a "key changed" warning the moment the new key shows up. If you want to remove @fede from the picture, add and verify an email. The code expires in 10 minutes, dies after 5 wrong guesses, and is traded once for a 15-minute single-use token. Completing a reset ends every existing session on the account. ──────────────────────────────────────────────────────────────────────── EMAIL ──────────────────────────────────────────────────────────────────────── Optional. You can sign up with nothing but a username. An address is only ever written to your account after you enter the code sent to it. Skip that step and nothing is stored. Not an unverified address, not a pending one. This is enforced on the server, not just in the interface: a hand-crafted signup request cannot plant an address either. Consequence: an address shown on an account is one that was actually proven. ──────────────────────────────────────────────────────────────────────── MODERATION AND WHO CAN DO WHAT ──────────────────────────────────────────────────────────────────────── @fede owns the site: sole account that can see other people's email addresses, and the only one not rate-limited on moderation actions. @fede, @kiv and @kivxo cannot be banned or deleted by anyone but the owner, and are the only accounts that can grant or revoke admin. This is matched by name, so those handles are reserved and cannot be taken by renaming into them. RSTPSW is an automated account. It cannot be banned or deleted by anyone at all, including the owner. Removing it would strand every account that has no email on file. Any other admin gets one destructive action per five minutes. Admins can ban and delete accounts. They cannot read messages; nobody can. Admins also get db.zekoro.one, a read-only view of the database. It lives on its own origin on purpose: it shows lots of user-written text, so any escaping mistake there can't reach zekoro.one, where unlocked keys are kept. That host serves nothing but the viewer, its sign-in and its data API, with its own session cookie. It's locked to admin accounts (anyone else gets a sign-in page, and the data API refuses them), and it never writes. Anything that could be used to log in as someone or attack them offline is shown only as "redacted" with its length: password/auth hashes, auth salts, session and reset tokens, OTP hashes, wrapped private keys, recovery blobs. Message ciphertext shows only its size. Email addresses are masked for every admin except the owner. Hidden columns can't be searched or sorted, since both would leak their contents a little at a time. What it does show (usernames, who's in which server, when things happened, message counts) is metadata the server already has; see SHARP EDGES. Rate limits, for the curious: signup 10/min per IP, login 8/min, prelogin 30/min, reset 5 per 10 min per IP and 3 per account, verification codes 3 per 5 min, sending 60/min, password changes 5 per 10 min, account upgrades 10 per 10 min. Usernames can be changed once a week. ──────────────────────────────────────────────────────────────────────── DELETION ──────────────────────────────────────────────────────────────────────── "Clear chat" is yours alone. It records a high-water mark rather than deleting rows, so clearing your copy never reaches into the other person's history. "Remove from list" hides a conversation from your sidebar; it stays recoverable under Deleted chats. Deleting an account removes its rows for real, and cascades to its messages. ──────────────────────────────────────────────────────────────────────── SHARP EDGES (read this one) ──────────────────────────────────────────────────────────────────────── Things that are true and that you should know before trusting this with anything that matters: No forward secrecy. Messages are sealed with long-term static keys, not a ratchet like Signal's. If your private key is ever stolen (from an unlocked device, or your key blob plus your password), every message ever sent to or from you can be decrypted, past and future. Changing your password re-wraps the same key; it does not help against a key that already leaked. A reset without a recovery code does start a new key, but old messages stay readable to whoever has the old one. Cloudflare terminates TLS. The site sits behind Cloudflare, which decrypts HTTPS before re-encrypting it to our origin. Message contents are still end-to-end encrypted inside that, so Cloudflare sees what our server sees (metadata, ciphertext), not your messages. The encryption code is served by the thing it protects you from. Your browser downloads app.js from us (through Cloudflare) every time. Whoever controls the server or that edge could ship a modified app.js that sends your password or key somewhere, and you would not notice. This is true of every web-based encrypted messenger. The iOS and desktop apps load the same web code, so they have the same property. Safety numbers help against key swaps, not against a malicious app.js. Synced passkeys are as strong as the account they sync with. A passkey kept in iCloud Keychain, Google Password Manager or a password manager can unlock your messages on any device that account reaches. Whoever gets into that Apple, Google or password-manager account can get into your Zekoro messages too. If that worries you, use a passkey that stays on one device or a security key, and protect the syncing account with its own passkey or 2FA. Settings shows which passkeys are synced. Pins are per device. A new browser trusts whatever key it sees first. Old messages are only half verified. Messages from before the envelope existed carry no context, so they're marked "unverified". Each device remembers the first enveloped message it saw in each chat and refuses any envelope-less message after it, so the server can't slip old ones back in later, but it could insert one among the old history on a device that has never opened that chat. Metadata is visible. Who talks to whom, when, how often, how big, group membership, and IP addresses (including in calls). Only content is hidden. An unlocked device is an unlocked account. If you tick "remember this device", the decrypted key sits in browser storage until you forget it. Voice channels are a peer to peer mesh, so they top out at 8 people, and everyone in a room learns everyone else's IP address, same as a 1:1 call, unless they turn on "Hide my IP address in calls". Server permissions are enforced by the server, not by cryptography. They decide who a message is encrypted to, so a server that lied about them could add itself as a reader of future channel messages. It would show up in the member list, and pinned keys still warn if anyone's key is swapped. ──────────────────────────────────────────────────────────────────────── APPS ──────────────────────────────────────────────────────────────────────── The desktop apps (Windows, Linux) are Tauri, not Electron: a system web view showing zekoro.one, with no Node.js in the page and no native API exposed to the site (its only capability is Tauri's core defaults, and remote pages get no access to it). A bug in the web app stays a web bug; it can't run code on your computer. The iPhone app is a web view too; it's no longer updated. ──────────────────────────────────────────────────────────────────────── SHAPE OF THE THING ──────────────────────────────────────────────────────────────────────── Cloudflare in front, nginx behind it, one Node process, SQLite on disk. The client is a single file of plain JavaScript with no framework and no build step. The code your browser runs is the code that was written, which matters more than usual when the code is doing your encryption. Crypto libraries: TweetNaCl (nacl.box, secretbox) and the browser's built-in WebCrypto (PBKDF2, AES-GCM, SHA-512). Server side: Node's crypto (scrypt). Sessions are HttpOnly, Secure, SameSite=Lax cookies. The page ships a strict Content-Security-Policy with no inline scripts, because with decrypted keys in memory, cross-site scripting is the attack that actually matters.