{"article":{"slug":"how-to-create-your-own-decentralized-messenger-protocol","title":"How to Create Your Own Decentralized Messenger Protocol","subtitle":null,"summary":"A from-scratch design for a federated, email-like messenger protocol: domain-based identity, discovery metadata, server signing keys, and end-to-end encrypted messages between servers.","content_type":"tutorial","language":"en","canonical_url":"https://karboosx.net/post/5j7jdDM3/how-to-create-your-own-decentralized-messenger-protocol","author":{"name":"Michał Karbowiak (karboosx)","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"Karboosx","url":"https://karboosx.net/","listing_slug":null,"listing":null},"topics":[{"name":"networking","slug":"networking","url":"https://listedarticles.com/topics/networking"},{"name":"security","slug":"security","url":"https://listedarticles.com/topics/security"},{"name":"tutorials","slug":"tutorials","url":"https://listedarticles.com/topics/tutorials"},{"name":"software-engineering","slug":"software-engineering","url":"https://listedarticles.com/topics/software-engineering"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":3017,"reading_minutes":13,"published_at":"2026-07-10T20:02:00.000Z","added_at":"2026-11-15T01:49:05.023Z","updated_at":"2026-11-15T01:49:05.023Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/how-to-create-your-own-decentralized-messenger-protocol","markdown_url":"https://listedarticles.com/articles/how-to-create-your-own-decentralized-messenger-protocol.md","example":false,"citation":"Michał Karbowiak (karboosx), Karboosx. \"How to Create Your Own Decentralized Messenger Protocol.\" 10 Jul 2026. https://karboosx.net/post/5j7jdDM3/how-to-create-your-own-decentralized-messenger-protocol (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://karboosx.net/post/5j7jdDM3/how-to-create-your-own-decentralized-messenger-protocol"},"body_markdown":"# How to Create Your Own Decentralized Messenger Protocol\n\nPublished July 10, 2026\n\n![](https://karboosx.net/img/myself.png?v=20261114-121720-fzsu)\nMichał Karbowiak (karboosx)\n\nLet's say you want to create a system where each server can \"join\" a network and start exchanging something with other members within that network. How would you approach such a task?\nYou could create a small centralized orchestrator that will accept join requests and handle that for the recipients, but that's not decentralized. What if we want a truly \"plug and play\" solution without any centralized servers?\nOne such solution is **federation**.\n\n![Federation fun image](https://karboosx.net/image/normal/6d04a9aa-2b37-4a99-a14b-8ca64199eae8.jpg)\n\n## What is federation\n\nA good example would be SMTP (the protocol for sending emails). It's mostly decentralized. Anyone can run their own mail server. There is no single central authority that says \"yes! this server can have email, but that one? NOOO!\".\nEach server communicates using a well-known protocol and exchanges information server-to-server.\nYou can even call it an \"API with known payload schemas\", although that is a bit of a simplification.\n\nLet's go with the email thing and start with the obvious. Have you ever considered why email addresses contain an `@<domain>` part? Why can't it just be `my_nick`?  \nIt's necessary to know which domain is responsible for that identity! duh!  \nThat domain plays a very important role in the whole federation exchange.  \nThat's because if you write from your email, let's say `[email protected]`, to `[email protected]`, the sending mail server will take that `y.com` part, do DNS discovery for MX records, connect to the mail server responsible for that domain, and start exchanging messages.\n\nThis is the core idea of federation: servers talk to each other directly after some \"discovery process\". In our small email example, the discovery part would be a DNS lookup for MX records.\n\n## Federated Messenger Protocol\n\nOk, but we came here to create our own messenger protocol, so let's start.\n\nFirst, we need to gather some requirements like good system (and in this case, protocol) designers.\n\n1. Let's assume that we want to have end-to-end encryption - so the server should only see encrypted message data, and end clients will handle encryption and decryption.\n2. We also don't want to blindly trust anyone who sends an HTTP request and says \"hello, I am x.com\".So we need a way to verify that a federation request was signed by a server that controls the source domain.\n3. Also, we don't want to make it super complicated, so let's drop any fancy things like attachments, multi-device solutions, groups, read receipts, etc. For now, we want to have a decentralized, simple text exchange with only one device. Welcome to the 90s! :D\n\nThat should be the basic minimum for our needs. So how do we even start doing it?\n\nLet's start with the easiest, and then move to more complex stuff.\n\n## User Identity\n\nLet's also assume that every server already has some users with registration, login, etc. So we don't spend a million years doing everything from scratch.  \nWe need to enforce that user identity will be like an email.  \nSo `<nickname>@<domain>`, otherwise our federation will not know who to call.\n\nThe important thing here is that `[email protected]` is not an email address. It only uses the same shape because the shape is useful. The domain tells other servers where to discover federation metadata.  \nWe could go with, for example, `x.com > adam`, `x.com#adam`, or `adam on x.com`. It's your call.\n\n## Discovery\n\nNow the first real work. Discovery is the part similar to the MX record lookup process mentioned earlier.\n\nWe have full freedom on how we want to handle this, so let's do it with a simple file on the server.\n\nFor this, we can use the typical `.well-known` directory.  \nIn our case, we can call our protocol `lnchat` (from LearN chat).  \nThis will be our first requirement for the protocol.\n\nServer MUST provide a file under:\n\n```\nGET /.well-known/lnchat.json\n```\n\nInside we can put the version and other important information that we will craft later in the article. For now, we can go with only the version:\n\n```\n{\n  \"protocol\": \"lnchat.federation.v1\"\n}\n```\n\nBy the way, it's good practice to always version protocols. It enforces the contract and saves you from a lot of headaches.\n\nWith this, servers can check if the servers we want to reach even support our protocol. If yes, they can pull all the necessary information from this one `.well-known` file.\n\n## End to End\n\n![Federation E2E Funny image](https://karboosx.net/image/normal/1c9723a2-75bc-4832-8d18-76c0536060ce.jpg)\nSince we want to have end-to-end encryption, we need client-side encryption keys.  \nUsually that means one private key that stays with the client, and one public key that the user's server can share with other servers.\n\n- The public key is used by senders as input to encryption for that user.\n- The private key is used by the receiver to decrypt it.\n\nThe private key MUST NOT be sent to the server as plaintext. If the server can read the private key, then the server can read the messages, and we don't really have end-to-end encryption anymore.\n\n> Important: if a server is responsible for publishing users' public keys, a malicious or compromised server could lie about a key. Real end-to-end encryption needs some way to notice that, for example contact key warnings, fingerprints, TOFU, or key transparency.\n\nSo we need an endpoint for sharing users' public keys. Every server should implement it as part of our protocol. So let's craft it!\n\nFirst, let's add information to our discovery file about where to look for the endpoint. This gives every server the ability to choose its own URLs.  \nIt's better not to enforce strict paths here as it may collide with already existing routes on the server.\n\n```\n{\n  \"protocol\": \"lnchat.federation.v1\",\n  \"endpoints\": {\n    \"resolve_users\": \"https://example.com/federation/v1/users/resolve\"\n  }\n}\n```\n\nBut the `resolve_users` URL could be a different URL on every server.\n\n### Resolving users\n\nThe `resolve_users` endpoint will be responsible for returning current public encryption keys for users from that server.  \nOther servers will call it before sending a message, so they know which key should be used for which recipient.\n\nWe can craft a schema for this endpoint like this:\n\n```\n{\n  \"protocol\": \"lnchat.federation.v1\",\n  \"users\": [\"[email protected]\", \"[email protected]\"]\n}\n```\n\n> Why an array of users and not just one? Let's imagine that it will be used in high-volume servers. We should offer a way to ease the performance.\n> If the server can resolve several users in one request, it will be much more performant - fewer HTTP calls.\n\nAnd for the response, let's do this:\n\n```\n{\n  \"protocol\": \"lnchat.federation.v1\",\n  \"status\": \"ok\",\n  \"users\": [\n    {\n      \"user\": \"[email protected]\",\n      \"status\": \"ok\",\n      \"key\": {\n        \"key_id\": \"adam-enc-2026-07-a\",\n        \"public_key\": \"base64url-raw-32-byte-x25519-public-key\"\n      }\n    },\n    {\n      \"user\": \"[email protected]\",\n      \"status\": \"not_deliverable\"\n    }\n  ]\n}\n```\n\nSo the user can expose a key with a `key_id` and `public_key`.  \nWhy do we need a `key_id`?  \nWell, imagine how the flow would look like.  \nThe client gets the user's public key and probably stores it in some cache, then sends messages using that key.  \nWhat if that key changes? The receiver will never decrypt it. We need to have a way to distinguish keys from each other and even show a warning that the key changed! Maybe it was compromised!\n\nI also added two statuses: `ok` and `not_deliverable`. `ok` is self-explanatory, but I added `not_deliverable` for cases where we don't have a public key for that user yet.  \nRemember that the user needs to generate those keys. We cannot safely do it on the backend if we want real end-to-end encryption.  \nSo there is a chance that we already have users who never generated them. We should clearly state that this user is not a valid user for receiving encrypted messages.\n\n### Publishing keys\n\nFor now, we only handled the endpoint for server-to-server key exchange. But how will that public key appear in the first place?\n\nThe user can use the Web Crypto API to generate keys, store the private key locally, and send the public key to the backend to keep it in the DB.\n\n```\nconst keyPair = await window.crypto.subtle.generateKey(\n    { name: \"X25519\" },\n    false,\n    [\"deriveBits\"]\n);\n\nconst publicKey = await window.crypto.subtle.exportKey(\n    \"raw\",\n    keyPair.publicKey\n);\n```\n\nGenerally, we should avoid exporting the private key outside of the client unless we really need to. Browsers can store `CryptoKey` objects in IndexedDB.\nIf the private key is non-extractable, it is harder to accidentally leak it as a string somewhere.\n\nThis key is not literally used to encrypt the text directly. It is used by the encryption method to create a shared secret between sender and receiver.\n\nSo how would the flow look from the user's perspective?\n\nsequenceDiagram\nparticipant C as Client\nparticipant IDB as IndexedDB\nparticipant HS as Home Server\nparticipant ES as Someone Else's Server\nC->>C: generate encryption keys\nC->>IDB: store private key\nC->>HS: store public\\_key\nES->>HS: get .well-known/lnchat.json\nES->>HS: call resolve\\_users\nHS->>ES: user\\_public\\_key\n\nHere we assume that our home server can store the `public_key`, and it will be exposed through the `resolve_users` endpoint according to our protocol schema.\n\n## Messaging\n\nNow we can resolve the recipient's public key. Great. But we still need to actually send something.\n\nFor the first version, let's keep the responsibility split simple:\n\n1. The client encrypts the message body.\n2. The home server validates the request, creates the federation envelope, and sends it to the recipient server.\n3. The recipient server gets the message, validates it, and stores it until the user requests it.\n4. The user decrypts messages using their private key.\n\nsequenceDiagram\nparticipant SC as Sender Client\nparticipant SS as Sender Server\nparticipant RS as Recipient Server\nparticipant RC as Recipient Client\nSC->>SS: ask for recipient public key\nSS->>RS: resolve\\_users\nRS-->>SS: public key + key\\_id\nSS-->>SC: public key + key\\_id\nSC->>SC: encrypt message body\nSC->>SS: encrypted message\nSS->>RS: federation message\nRS->>RC: encrypted message\nRC->>RC: decrypt message body\n\nFirst, the client encrypts the message locally.\nThen the client could send something like this to its own server:\n\n```\n{\n  \"recipient\": \"[email protected]\",\n  \"recipient_key_id\": \"barney-enc-2026-07-a\",\n  \"encapsulated_key\": \"base64url-hpke-enc\",\n  \"ciphertext\": \"base64url-ciphertext\"\n}\n```\n\n> We will talk about the `encapsulated_key` and `ciphertext` in a minute. So for now let's just accept that it's a \"secret message\".\n\nAnd the plaintext inside the ciphertext can be very small:\n\n```\n{\n  \"protocol\": \"lnchat.message.v1\",\n  \"type\": \"text\",\n  \"body\": \"hello\"\n}\n```\n\nOr the actual message could be simple text, but it's better to pack it in some sort of format so we can send more metadata alongside the message itself. Maybe later this could be used for a simple version of attachments, etc.\n\nThe server then creates its own HTTP request and sends it to the `Recipient Server`. But to which endpoint?\n\nWell, to achieve that we need to add one more endpoint to our discovery file.\n\n```\n{\n  ...\n  \"endpoints\": {\n    ...\n    \"send_messages\": \"https://example.com/federation/v1/message\"\n  }\n}\n```\n\nNow `Sender Server` can take the encryption data and send it to `Recipient Server`.\n\nPayload can look like this:\n\n```\n{\n  \"protocol\": \"lnchat.federation.v1\",\n  \"message_id\": \"019f47a9-b138-79d2-8ec3-38a2a9326955\",\n  \"sender\": \"[email protected]\",\n  \"recipient\": \"[email protected]\",\n  \"recipient_key_id\": \"barney-enc-2026-07-a\",\n  \"encapsulated_key\": \"base64url-hpke-enc\",\n  \"ciphertext\": \"base64url-ciphertext\"\n}\n```\n\nNotice that we added `message_id` and `sender`, but they were not present in the client message. This is intentional. We shouldn't trust the client to provide the real `sender` id. The user is already authenticated, so we can always put their name there.  \nAnd `message_id` is there for idempotency. If the server sends the same message twice, and the first one was already processed, we should reject the second one.  \nThe `message_id` should be a randomly generated string. We can go with `UUIDv7`, for example.\n\n`recipient_key_id` should be the same id we get from the `resolve_users` endpoint. It tells the recipient which key was used to encrypt the message.\n\n## So how to encrypt payload?\n\nWhat's up with the `encapsulated_key`, you may ask?\n\nWell, for a modern messaging system it's good to use something called `HPKE`.\n\nHPKE itself is a bit too heavy to explain fully in this post, so let's use a simpler mental model.\nEncrypting directly with asymmetric keys can be computationally heavy. So the idea is:\n\n1. We generate a new symmetric key. This is the kind of key where the same key encrypts and decrypts the message.\n2. We encrypt the message with the symmetric key we just generated.\n3. We encapsulate that symmetric key with the recipient's public key and send that encapsulated key alongside the message.\n4. The recipient can recover the symmetric key and then use it to decrypt the message.\n\nThis is not a precise HPKE specification, but it is close enough to understand why the payload has two parts: the encapsulated key material and the ciphertext.\n\nSo how would we do it in JS? Better not to do it ourselves anymore using raw crypto methods. Let's delegate it to smarter people from GitHub, like this: <https://github.com/dajiaji/hpke-js>\n\nFor readability, let's assume that `recipientPublicKey` is already imported from the resolved base64url public key.\n\n```\nimport {\n    Aes256Gcm,\n    CipherSuite,\n    HkdfSha256,\n} from \"@hpke/core\";\nimport { DhkemX25519HkdfSha256 } from \"@hpke/dhkem-x25519\";\n\nconst suite = new CipherSuite({\n    kem: new DhkemX25519HkdfSha256(),\n    kdf: new HkdfSha256(),\n    aead: new Aes256Gcm(),\n});\n\nfunction b64url(bytes) {\n    return new Uint8Array(bytes).toBase64({\n        alphabet: \"base64url\",\n        omitPadding: true,\n    });\n}\n\nconst plaintext = new TextEncoder().encode(JSON.stringify({\n    protocol: \"lnchat.message.v1\",\n    type: \"text\",\n    body: \"hello\",\n}));\n\nconst sender = await suite.createSenderContext({\n    recipientPublicKey,\n});\n\nconst ciphertext = await sender.seal(plaintext);\n\nconst payload = {\n    recipient: \"[email protected]\",\n    recipient_key_id: \"barney-enc-2026-07-a\",\n    encapsulated_key: b64url(sender.enc),\n    ciphertext: b64url(ciphertext),\n};\n```\n\n## Signing server messages\n\nSo we can discover servers, resolve users, get users' keys, and send encrypted messages. Nice.\nBut we still have one big problem.\n\nHow does `y.com` know that the message really came from `x.com`?\nAnyone can send an HTTP request and put this in JSON:\n\n```\n{\n  \"sender\": \"[email protected]\"\n}\n```\n\nThat proves nothing. So federation requests need to be signed by the sending server.\n![Signing machine](https://karboosx.net/image/normal/d117569b-1101-40e9-8060-86be6a4df531.jpg)\n\nWe need a separate key pair. Do not mix it with user encryption keys.\n\n- User encryption keys are for message content.\n- Server signing keys are for proving that a federation request came from a specific server.\n\nSo let's add yet another field to the discovery file. This time it will be the server's own public key.\n\n```\n{\n  \"protocol\": \"lnchat.federation.v1\",\n  \"server_keys\": [\n    {\n      \"key_id\": \"2026-07-ed25519-a\",\n      \"public_key\": \"base64url-ed25519-spki-der-public-key\"\n    }\n  ],\n  ...\n}\n```\n\nTo generate keys, you can probably use any modern cryptographic library. For example:\n\n```\nimport { generateKeyPairSync } from \"node:crypto\";\n\nconst { publicKey, privateKey } = generateKeyPairSync(\"ed25519\", {\n    privateKeyEncoding: {\n        type: \"pkcs8\",\n        format: \"pem\",\n    },\n});\n\nconst publicKeyDer = publicKey.export({\n    type: \"spki\",\n    format: \"der\",\n});\n\nstorage.savePrivateKey(privateKey);\ndiscovery.storePublicKey(publicKeyDer.toString(\"base64url\"));\n```\n\n> Remember to save the private key somewhere safe on the server, and publish the public key in the discovery file.\n\nNow when `x.com` sends a request to `y.com`, it also has to send a few headers:\n\n```\nLNChat-Source-Domain: x.com\nLNChat-Target-Domain: y.com\nLNChat-Key-Id: 2026-07-ed25519-a\nLNChat-Timestamp: 2026-07-09T12:00:00Z\nLNChat-Request-Id: 6fb10f56-7b5f-4f68-9b17-6c07cdb3c4d8\nLNChat-Body-SHA256: base64url-sha256-of-body\nLNChat-Signature: base64url-ed25519-signature\n```\n\nThe idea is:\n\n1. `x.com` creates the request body.\n2. `x.com` hashes the body.\n3. `x.com` signs a strict text representation of the request using its private server key.\n4. `y.com` downloads the public server key from `x.com` discovery.\n5. `y.com` verifies the signature.\n\nAnd here one boring detail matters a lot: both servers must build exactly the same string.  \nSame new lines. Same path. Same timestamp format. Same hash.  \nIf one server signs a slightly different string than the other server verifies, verification will fail.\n\nThat strict text representation could look like this:\n\n```\nLNCHAT-FEDERATION-V1\nPOST\n/federation/v1/message\nx.com\ny.com\n2026-07-09T12:00:00Z\n6fb10f56-7b5f-4f68-9b17-6c07cdb3c4d8\nbase64url-sha256-of-body\n```\n\nWhy do we also have to send `version`, `method`, and `URL`? Well, the `send_messages` endpoint should enforce signing. But why not require all federation endpoints to require such a signature? It's good practice to have this concept that everything coming to your server can be verified as coming from the server it claims to come from.\n\nBy the way, notice that we signed a hash of the body, not the full body?\n\n```\nbase64url-sha256-of-body\n```\n\nWell, it's faster that way to sign only a small text, not 20MB. Remember, this is signing, not encrypting.  \nThe signature proves that the sender had the private server key and signed exactly this canonical request. The timestamp and request id are also important because they help the receiver reject old or replayed requests.\n\nSo on the sending server you sign:\n\n```\nimport { sign, verify } from \"node:crypto\";\n\nconst canonicalRequest = [\n    \"LNCHAT-FEDERATION-V1\",\n    \"POST\",\n    \"/federation/v1/message\",\n    \"x.com\",\n    \"y.com\",\n    \"2026-07-09T12:00:00Z\",\n    \"6fb10f56-7b5f-4f68-9b17-6c07cdb3c4d8\",\n    \"base64url-sha256-of-body\",\n].join(\"\\n\");\n\nconst signature = sign(\n    null,\n    Buffer.from(canonicalRequest, \"utf8\"),\n    privateKey\n);\nconsole.log(signature.toString(\"base64url\"));\n```\n\nAnd on the receiving server you have to verify. But in order to do it, you first need to:\n\n1. check the `LNChat-Source-Domain` header to determine who is calling\n2. request the `.well-known/lnchat.json` file and get the public key from the domain of the `LNChat-Source-Domain`\n3. decode the public key and signature from base64url\n4. build the `canonicalRequest` text\n5. verify that text using the public key from the discovery file and the signature from the `LNChat-Signature` header\n\n> Security note: avoid SSRF (Server-Side Request Forgery), where a remote server tricks your server into calling internal or private network addresses. When fetching `.well-known/lnchat.json`, validate the source domain, require HTTPS with valid certificates, and do not follow redirects to private or local network addresses.\n\n```\nimport { createPublicKey, verify } from \"node:crypto\";\n\nconst publicKey = createPublicKey({\n    key: Buffer.from(discoveryPublicKey, \"base64url\"),\n    type: \"spki\",\n    format: \"der\",\n});\n\nconst signature = Buffer.from(signatureHeader, \"base64url\");\n\nconst ok = verify(\n    null,\n    Buffer.from(canonicalRequest, \"utf8\"),\n    publicKey,\n    signature\n);\n\nconsole.log(ok);\n```\n\nIf `ok` is true, we know that this request was signed by someone who has the private key matching the public key from discovery.\n\nThat still does not prove that the user personally typed the message.  \nIt proves that server `x.com` accepted the message and signed the federation request.  \nBut in this simple version we already trust our home server to handle login, sender identity, and routing. So for now that is enough.\n\nsequenceDiagram\nparticipant HS as Home Server\nparticipant ES as Someone Else's Server\nHS->>HS: keep server signing private key\nHS->>ES: send signed federation request\nES->>HS: fetch discovery\nHS-->>ES: public signing key\nES->>ES: verify signature using public key\nES->>ES: process request if valid\n\nAnd that's the basic shape of federation:\n\n1. Identity uses a domain.\n2. Domain exposes discovery metadata.\n3. Servers use discovery to find endpoints and public server keys.\n4. Clients use recipient public keys to encrypt messages.\n5. Servers use signing keys to authenticate federation requests.\n","body_html":"<h1 id=\"how-to-create-your-own-decentralized-messenger-protocol\">How to Create Your Own Decentralized Messenger Protocol</h1>\n<p>Published July 10, 2026</p>\n<figure><img src=\"https://karboosx.net/img/myself.png?v=20261114-121720-fzsu\" alt=\"\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p>Michał Karbowiak (karboosx)</p>\n<p>Let&#39;s say you want to create a system where each server can &quot;join&quot; a network and start exchanging something with other members within that network. How would you approach such a task?\nYou could create a small centralized orchestrator that will accept join requests and handle that for the recipients, but that&#39;s not decentralized. What if we want a truly &quot;plug and play&quot; solution without any centralized servers?\nOne such solution is <strong>federation</strong>.</p>\n<figure><img src=\"https://karboosx.net/image/normal/6d04a9aa-2b37-4a99-a14b-8ca64199eae8.jpg\" alt=\"Federation fun image\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<h2 id=\"what-is-federation\">What is federation</h2>\n<p>A good example would be SMTP (the protocol for sending emails). It&#39;s mostly decentralized. Anyone can run their own mail server. There is no single central authority that says &quot;yes! this server can have email, but that one? NOOO!&quot;.\nEach server communicates using a well-known protocol and exchanges information server-to-server.\nYou can even call it an &quot;API with known payload schemas&quot;, although that is a bit of a simplification.</p>\n<p>Let&#39;s go with the email thing and start with the obvious. Have you ever considered why email addresses contain an <code>@&lt;domain&gt;</code> part? Why can&#39;t it just be <code>my_nick</code>?<br />\nIt&#39;s necessary to know which domain is responsible for that identity! duh!<br />\nThat domain plays a very important role in the whole federation exchange.<br />\nThat&#39;s because if you write from your email, let&#39;s say <code>[email protected]</code>, to <code>[email protected]</code>, the sending mail server will take that <code>y.com</code> part, do DNS discovery for MX records, connect to the mail server responsible for that domain, and start exchanging messages.</p>\n<p>This is the core idea of federation: servers talk to each other directly after some &quot;discovery process&quot;. In our small email example, the discovery part would be a DNS lookup for MX records.</p>\n<h2 id=\"federated-messenger-protocol\">Federated Messenger Protocol</h2>\n<p>Ok, but we came here to create our own messenger protocol, so let&#39;s start.</p>\n<p>First, we need to gather some requirements like good system (and in this case, protocol) designers.</p>\n<ol><li>Let&#39;s assume that we want to have end-to-end encryption - so the server should only see encrypted message data, and end clients will handle encryption and decryption.</li><li>We also don&#39;t want to blindly trust anyone who sends an HTTP request and says &quot;hello, I am x.com&quot;.So we need a way to verify that a federation request was signed by a server that controls the source domain.</li><li>Also, we don&#39;t want to make it super complicated, so let&#39;s drop any fancy things like attachments, multi-device solutions, groups, read receipts, etc. For now, we want to have a decentralized, simple text exchange with only one device. Welcome to the 90s! :D</li></ol>\n<p>That should be the basic minimum for our needs. So how do we even start doing it?</p>\n<p>Let&#39;s start with the easiest, and then move to more complex stuff.</p>\n<h2 id=\"user-identity\">User Identity</h2>\n<p>Let&#39;s also assume that every server already has some users with registration, login, etc. So we don&#39;t spend a million years doing everything from scratch.<br />\nWe need to enforce that user identity will be like an email.<br />\nSo <code>&lt;nickname&gt;@&lt;domain&gt;</code>, otherwise our federation will not know who to call.</p>\n<p>The important thing here is that <code>[email protected]</code> is not an email address. It only uses the same shape because the shape is useful. The domain tells other servers where to discover federation metadata.<br />\nWe could go with, for example, <code>x.com &gt; adam</code>, <code>x.com#adam</code>, or <code>adam on x.com</code>. It&#39;s your call.</p>\n<h2 id=\"discovery\">Discovery</h2>\n<p>Now the first real work. Discovery is the part similar to the MX record lookup process mentioned earlier.</p>\n<p>We have full freedom on how we want to handle this, so let&#39;s do it with a simple file on the server.</p>\n<p>For this, we can use the typical <code>.well-known</code> directory.<br />\nIn our case, we can call our protocol <code>lnchat</code> (from LearN chat).<br />\nThis will be our first requirement for the protocol.</p>\n<p>Server MUST provide a file under:</p>\n<pre><code>GET /.well-known/lnchat.json</code></pre>\n<p>Inside we can put the version and other important information that we will craft later in the article. For now, we can go with only the version:</p>\n<pre><code>{\n  &quot;protocol&quot;: &quot;lnchat.federation.v1&quot;\n}</code></pre>\n<p>By the way, it&#39;s good practice to always version protocols. It enforces the contract and saves you from a lot of headaches.</p>\n<p>With this, servers can check if the servers we want to reach even support our protocol. If yes, they can pull all the necessary information from this one <code>.well-known</code> file.</p>\n<h2 id=\"end-to-end\">End to End</h2>\n<figure><img src=\"https://karboosx.net/image/normal/1c9723a2-75bc-4832-8d18-76c0536060ce.jpg\" alt=\"Federation E2E Funny image\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p>Since we want to have end-to-end encryption, we need client-side encryption keys.<br />\nUsually that means one private key that stays with the client, and one public key that the user&#39;s server can share with other servers.</p>\n<ul><li>The public key is used by senders as input to encryption for that user.</li><li>The private key is used by the receiver to decrypt it.</li></ul>\n<p>The private key MUST NOT be sent to the server as plaintext. If the server can read the private key, then the server can read the messages, and we don&#39;t really have end-to-end encryption anymore.</p>\n<blockquote><p>Important: if a server is responsible for publishing users&#39; public keys, a malicious or compromised server could lie about a key. Real end-to-end encryption needs some way to notice that, for example contact key warnings, fingerprints, TOFU, or key transparency.</p></blockquote>\n<p>So we need an endpoint for sharing users&#39; public keys. Every server should implement it as part of our protocol. So let&#39;s craft it!</p>\n<p>First, let&#39;s add information to our discovery file about where to look for the endpoint. This gives every server the ability to choose its own URLs.<br />\nIt&#39;s better not to enforce strict paths here as it may collide with already existing routes on the server.</p>\n<pre><code>{\n  &quot;protocol&quot;: &quot;lnchat.federation.v1&quot;,\n  &quot;endpoints&quot;: {\n    &quot;resolve_users&quot;: &quot;https://example.com/federation/v1/users/resolve&quot;\n  }\n}</code></pre>\n<p>But the <code>resolve_users</code> URL could be a different URL on every server.</p>\n<h3 id=\"resolving-users\">Resolving users</h3>\n<p>The <code>resolve_users</code> endpoint will be responsible for returning current public encryption keys for users from that server.<br />\nOther servers will call it before sending a message, so they know which key should be used for which recipient.</p>\n<p>We can craft a schema for this endpoint like this:</p>\n<pre><code>{\n  &quot;protocol&quot;: &quot;lnchat.federation.v1&quot;,\n  &quot;users&quot;: [&quot;[email protected]&quot;, &quot;[email protected]&quot;]\n}</code></pre>\n<blockquote><p>Why an array of users and not just one? Let&#39;s imagine that it will be used in high-volume servers. We should offer a way to ease the performance.\nIf the server can resolve several users in one request, it will be much more performant - fewer HTTP calls.</p></blockquote>\n<p>And for the response, let&#39;s do this:</p>\n<pre><code>{\n  &quot;protocol&quot;: &quot;lnchat.federation.v1&quot;,\n  &quot;status&quot;: &quot;ok&quot;,\n  &quot;users&quot;: [\n    {\n      &quot;user&quot;: &quot;[email protected]&quot;,\n      &quot;status&quot;: &quot;ok&quot;,\n      &quot;key&quot;: {\n        &quot;key_id&quot;: &quot;adam-enc-2026-07-a&quot;,\n        &quot;public_key&quot;: &quot;base64url-raw-32-byte-x25519-public-key&quot;\n      }\n    },\n    {\n      &quot;user&quot;: &quot;[email protected]&quot;,\n      &quot;status&quot;: &quot;not_deliverable&quot;\n    }\n  ]\n}</code></pre>\n<p>So the user can expose a key with a <code>key_id</code> and <code>public_key</code>.<br />\nWhy do we need a <code>key_id</code>?<br />\nWell, imagine how the flow would look like.<br />\nThe client gets the user&#39;s public key and probably stores it in some cache, then sends messages using that key.<br />\nWhat if that key changes? The receiver will never decrypt it. We need to have a way to distinguish keys from each other and even show a warning that the key changed! Maybe it was compromised!</p>\n<p>I also added two statuses: <code>ok</code> and <code>not_deliverable</code>. <code>ok</code> is self-explanatory, but I added <code>not_deliverable</code> for cases where we don&#39;t have a public key for that user yet.<br />\nRemember that the user needs to generate those keys. We cannot safely do it on the backend if we want real end-to-end encryption.<br />\nSo there is a chance that we already have users who never generated them. We should clearly state that this user is not a valid user for receiving encrypted messages.</p>\n<h3 id=\"publishing-keys\">Publishing keys</h3>\n<p>For now, we only handled the endpoint for server-to-server key exchange. But how will that public key appear in the first place?</p>\n<p>The user can use the Web Crypto API to generate keys, store the private key locally, and send the public key to the backend to keep it in the DB.</p>\n<pre><code>const keyPair = await window.crypto.subtle.generateKey(\n    { name: &quot;X25519&quot; },\n    false,\n    [&quot;deriveBits&quot;]\n);\n\nconst publicKey = await window.crypto.subtle.exportKey(\n    &quot;raw&quot;,\n    keyPair.publicKey\n);</code></pre>\n<p>Generally, we should avoid exporting the private key outside of the client unless we really need to. Browsers can store <code>CryptoKey</code> objects in IndexedDB.\nIf the private key is non-extractable, it is harder to accidentally leak it as a string somewhere.</p>\n<p>This key is not literally used to encrypt the text directly. It is used by the encryption method to create a shared secret between sender and receiver.</p>\n<p>So how would the flow look from the user&#39;s perspective?</p>\n<p>sequenceDiagram\nparticipant C as Client\nparticipant IDB as IndexedDB\nparticipant HS as Home Server\nparticipant ES as Someone Else&#39;s Server\nC-&gt;&gt;C: generate encryption keys\nC-&gt;&gt;IDB: store private key\nC-&gt;&gt;HS: store public_key\nES-&gt;&gt;HS: get .well-known/lnchat.json\nES-&gt;&gt;HS: call resolve_users\nHS-&gt;&gt;ES: user_public_key</p>\n<p>Here we assume that our home server can store the <code>public_key</code>, and it will be exposed through the <code>resolve_users</code> endpoint according to our protocol schema.</p>\n<h2 id=\"messaging\">Messaging</h2>\n<p>Now we can resolve the recipient&#39;s public key. Great. But we still need to actually send something.</p>\n<p>For the first version, let&#39;s keep the responsibility split simple:</p>\n<ol><li>The client encrypts the message body.</li><li>The home server validates the request, creates the federation envelope, and sends it to the recipient server.</li><li>The recipient server gets the message, validates it, and stores it until the user requests it.</li><li>The user decrypts messages using their private key.</li></ol>\n<p>sequenceDiagram\nparticipant SC as Sender Client\nparticipant SS as Sender Server\nparticipant RS as Recipient Server\nparticipant RC as Recipient Client\nSC-&gt;&gt;SS: ask for recipient public key\nSS-&gt;&gt;RS: resolve_users\nRS--&gt;&gt;SS: public key + key_id\nSS--&gt;&gt;SC: public key + key_id\nSC-&gt;&gt;SC: encrypt message body\nSC-&gt;&gt;SS: encrypted message\nSS-&gt;&gt;RS: federation message\nRS-&gt;&gt;RC: encrypted message\nRC-&gt;&gt;RC: decrypt message body</p>\n<p>First, the client encrypts the message locally.\nThen the client could send something like this to its own server:</p>\n<pre><code>{\n  &quot;recipient&quot;: &quot;[email protected]&quot;,\n  &quot;recipient_key_id&quot;: &quot;barney-enc-2026-07-a&quot;,\n  &quot;encapsulated_key&quot;: &quot;base64url-hpke-enc&quot;,\n  &quot;ciphertext&quot;: &quot;base64url-ciphertext&quot;\n}</code></pre>\n<blockquote><p>We will talk about the <code>encapsulated_key</code> and <code>ciphertext</code> in a minute. So for now let&#39;s just accept that it&#39;s a &quot;secret message&quot;.</p></blockquote>\n<p>And the plaintext inside the ciphertext can be very small:</p>\n<pre><code>{\n  &quot;protocol&quot;: &quot;lnchat.message.v1&quot;,\n  &quot;type&quot;: &quot;text&quot;,\n  &quot;body&quot;: &quot;hello&quot;\n}</code></pre>\n<p>Or the actual message could be simple text, but it&#39;s better to pack it in some sort of format so we can send more metadata alongside the message itself. Maybe later this could be used for a simple version of attachments, etc.</p>\n<p>The server then creates its own HTTP request and sends it to the <code>Recipient Server</code>. But to which endpoint?</p>\n<p>Well, to achieve that we need to add one more endpoint to our discovery file.</p>\n<pre><code>{\n  ...\n  &quot;endpoints&quot;: {\n    ...\n    &quot;send_messages&quot;: &quot;https://example.com/federation/v1/message&quot;\n  }\n}</code></pre>\n<p>Now <code>Sender Server</code> can take the encryption data and send it to <code>Recipient Server</code>.</p>\n<p>Payload can look like this:</p>\n<pre><code>{\n  &quot;protocol&quot;: &quot;lnchat.federation.v1&quot;,\n  &quot;message_id&quot;: &quot;019f47a9-b138-79d2-8ec3-38a2a9326955&quot;,\n  &quot;sender&quot;: &quot;[email protected]&quot;,\n  &quot;recipient&quot;: &quot;[email protected]&quot;,\n  &quot;recipient_key_id&quot;: &quot;barney-enc-2026-07-a&quot;,\n  &quot;encapsulated_key&quot;: &quot;base64url-hpke-enc&quot;,\n  &quot;ciphertext&quot;: &quot;base64url-ciphertext&quot;\n}</code></pre>\n<p>Notice that we added <code>message_id</code> and <code>sender</code>, but they were not present in the client message. This is intentional. We shouldn&#39;t trust the client to provide the real <code>sender</code> id. The user is already authenticated, so we can always put their name there.<br />\nAnd <code>message_id</code> is there for idempotency. If the server sends the same message twice, and the first one was already processed, we should reject the second one.<br />\nThe <code>message_id</code> should be a randomly generated string. We can go with <code>UUIDv7</code>, for example.</p>\n<p><code>recipient_key_id</code> should be the same id we get from the <code>resolve_users</code> endpoint. It tells the recipient which key was used to encrypt the message.</p>\n<h2 id=\"so-how-to-encrypt-payload\">So how to encrypt payload?</h2>\n<p>What&#39;s up with the <code>encapsulated_key</code>, you may ask?</p>\n<p>Well, for a modern messaging system it&#39;s good to use something called <code>HPKE</code>.</p>\n<p>HPKE itself is a bit too heavy to explain fully in this post, so let&#39;s use a simpler mental model.\nEncrypting directly with asymmetric keys can be computationally heavy. So the idea is:</p>\n<ol><li>We generate a new symmetric key. This is the kind of key where the same key encrypts and decrypts the message.</li><li>We encrypt the message with the symmetric key we just generated.</li><li>We encapsulate that symmetric key with the recipient&#39;s public key and send that encapsulated key alongside the message.</li><li>The recipient can recover the symmetric key and then use it to decrypt the message.</li></ol>\n<p>This is not a precise HPKE specification, but it is close enough to understand why the payload has two parts: the encapsulated key material and the ciphertext.</p>\n<p>So how would we do it in JS? Better not to do it ourselves anymore using raw crypto methods. Let&#39;s delegate it to smarter people from GitHub, like this: <a href=\"https://github.com/dajiaji/hpke-js\" rel=\"nofollow ugc noopener\">https://github.com/dajiaji/hpke-js</a></p>\n<p>For readability, let&#39;s assume that <code>recipientPublicKey</code> is already imported from the resolved base64url public key.</p>\n<pre><code>import {\n    Aes256Gcm,\n    CipherSuite,\n    HkdfSha256,\n} from &quot;@hpke/core&quot;;\nimport { DhkemX25519HkdfSha256 } from &quot;@hpke/dhkem-x25519&quot;;\n\nconst suite = new CipherSuite({\n    kem: new DhkemX25519HkdfSha256(),\n    kdf: new HkdfSha256(),\n    aead: new Aes256Gcm(),\n});\n\nfunction b64url(bytes) {\n    return new Uint8Array(bytes).toBase64({\n        alphabet: &quot;base64url&quot;,\n        omitPadding: true,\n    });\n}\n\nconst plaintext = new TextEncoder().encode(JSON.stringify({\n    protocol: &quot;lnchat.message.v1&quot;,\n    type: &quot;text&quot;,\n    body: &quot;hello&quot;,\n}));\n\nconst sender = await suite.createSenderContext({\n    recipientPublicKey,\n});\n\nconst ciphertext = await sender.seal(plaintext);\n\nconst payload = {\n    recipient: &quot;[email protected]&quot;,\n    recipient_key_id: &quot;barney-enc-2026-07-a&quot;,\n    encapsulated_key: b64url(sender.enc),\n    ciphertext: b64url(ciphertext),\n};</code></pre>\n<h2 id=\"signing-server-messages\">Signing server messages</h2>\n<p>So we can discover servers, resolve users, get users&#39; keys, and send encrypted messages. Nice.\nBut we still have one big problem.</p>\n<p>How does <code>y.com</code> know that the message really came from <code>x.com</code>?\nAnyone can send an HTTP request and put this in JSON:</p>\n<pre><code>{\n  &quot;sender&quot;: &quot;[email protected]&quot;\n}</code></pre>\n<p>That proves nothing. So federation requests need to be signed by the sending server.\n<img src=\"https://karboosx.net/image/normal/d117569b-1101-40e9-8060-86be6a4df531.jpg\" alt=\"Signing machine\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></p>\n<p>We need a separate key pair. Do not mix it with user encryption keys.</p>\n<ul><li>User encryption keys are for message content.</li><li>Server signing keys are for proving that a federation request came from a specific server.</li></ul>\n<p>So let&#39;s add yet another field to the discovery file. This time it will be the server&#39;s own public key.</p>\n<pre><code>{\n  &quot;protocol&quot;: &quot;lnchat.federation.v1&quot;,\n  &quot;server_keys&quot;: [\n    {\n      &quot;key_id&quot;: &quot;2026-07-ed25519-a&quot;,\n      &quot;public_key&quot;: &quot;base64url-ed25519-spki-der-public-key&quot;\n    }\n  ],\n  ...\n}</code></pre>\n<p>To generate keys, you can probably use any modern cryptographic library. For example:</p>\n<pre><code>import { generateKeyPairSync } from &quot;node:crypto&quot;;\n\nconst { publicKey, privateKey } = generateKeyPairSync(&quot;ed25519&quot;, {\n    privateKeyEncoding: {\n        type: &quot;pkcs8&quot;,\n        format: &quot;pem&quot;,\n    },\n});\n\nconst publicKeyDer = publicKey.export({\n    type: &quot;spki&quot;,\n    format: &quot;der&quot;,\n});\n\nstorage.savePrivateKey(privateKey);\ndiscovery.storePublicKey(publicKeyDer.toString(&quot;base64url&quot;));</code></pre>\n<blockquote><p>Remember to save the private key somewhere safe on the server, and publish the public key in the discovery file.</p></blockquote>\n<p>Now when <code>x.com</code> sends a request to <code>y.com</code>, it also has to send a few headers:</p>\n<pre><code>LNChat-Source-Domain: x.com\nLNChat-Target-Domain: y.com\nLNChat-Key-Id: 2026-07-ed25519-a\nLNChat-Timestamp: 2026-07-09T12:00:00Z\nLNChat-Request-Id: 6fb10f56-7b5f-4f68-9b17-6c07cdb3c4d8\nLNChat-Body-SHA256: base64url-sha256-of-body\nLNChat-Signature: base64url-ed25519-signature</code></pre>\n<p>The idea is:</p>\n<ol><li><code>x.com</code> creates the request body.</li><li><code>x.com</code> hashes the body.</li><li><code>x.com</code> signs a strict text representation of the request using its private server key.</li><li><code>y.com</code> downloads the public server key from <code>x.com</code> discovery.</li><li><code>y.com</code> verifies the signature.</li></ol>\n<p>And here one boring detail matters a lot: both servers must build exactly the same string.<br />\nSame new lines. Same path. Same timestamp format. Same hash.<br />\nIf one server signs a slightly different string than the other server verifies, verification will fail.</p>\n<p>That strict text representation could look like this:</p>\n<pre><code>LNCHAT-FEDERATION-V1\nPOST\n/federation/v1/message\nx.com\ny.com\n2026-07-09T12:00:00Z\n6fb10f56-7b5f-4f68-9b17-6c07cdb3c4d8\nbase64url-sha256-of-body</code></pre>\n<p>Why do we also have to send <code>version</code>, <code>method</code>, and <code>URL</code>? Well, the <code>send_messages</code> endpoint should enforce signing. But why not require all federation endpoints to require such a signature? It&#39;s good practice to have this concept that everything coming to your server can be verified as coming from the server it claims to come from.</p>\n<p>By the way, notice that we signed a hash of the body, not the full body?</p>\n<pre><code>base64url-sha256-of-body</code></pre>\n<p>Well, it&#39;s faster that way to sign only a small text, not 20MB. Remember, this is signing, not encrypting.<br />\nThe signature proves that the sender had the private server key and signed exactly this canonical request. The timestamp and request id are also important because they help the receiver reject old or replayed requests.</p>\n<p>So on the sending server you sign:</p>\n<pre><code>import { sign, verify } from &quot;node:crypto&quot;;\n\nconst canonicalRequest = [\n    &quot;LNCHAT-FEDERATION-V1&quot;,\n    &quot;POST&quot;,\n    &quot;/federation/v1/message&quot;,\n    &quot;x.com&quot;,\n    &quot;y.com&quot;,\n    &quot;2026-07-09T12:00:00Z&quot;,\n    &quot;6fb10f56-7b5f-4f68-9b17-6c07cdb3c4d8&quot;,\n    &quot;base64url-sha256-of-body&quot;,\n].join(&quot;\\n&quot;);\n\nconst signature = sign(\n    null,\n    Buffer.from(canonicalRequest, &quot;utf8&quot;),\n    privateKey\n);\nconsole.log(signature.toString(&quot;base64url&quot;));</code></pre>\n<p>And on the receiving server you have to verify. But in order to do it, you first need to:</p>\n<ol><li>check the <code>LNChat-Source-Domain</code> header to determine who is calling</li><li>request the <code>.well-known/lnchat.json</code> file and get the public key from the domain of the <code>LNChat-Source-Domain</code></li><li>decode the public key and signature from base64url</li><li>build the <code>canonicalRequest</code> text</li><li>verify that text using the public key from the discovery file and the signature from the <code>LNChat-Signature</code> header</li></ol>\n<blockquote><p>Security note: avoid SSRF (Server-Side Request Forgery), where a remote server tricks your server into calling internal or private network addresses. When fetching <code>.well-known/lnchat.json</code>, validate the source domain, require HTTPS with valid certificates, and do not follow redirects to private or local network addresses.</p></blockquote>\n<pre><code>import { createPublicKey, verify } from &quot;node:crypto&quot;;\n\nconst publicKey = createPublicKey({\n    key: Buffer.from(discoveryPublicKey, &quot;base64url&quot;),\n    type: &quot;spki&quot;,\n    format: &quot;der&quot;,\n});\n\nconst signature = Buffer.from(signatureHeader, &quot;base64url&quot;);\n\nconst ok = verify(\n    null,\n    Buffer.from(canonicalRequest, &quot;utf8&quot;),\n    publicKey,\n    signature\n);\n\nconsole.log(ok);</code></pre>\n<p>If <code>ok</code> is true, we know that this request was signed by someone who has the private key matching the public key from discovery.</p>\n<p>That still does not prove that the user personally typed the message.<br />\nIt proves that server <code>x.com</code> accepted the message and signed the federation request.<br />\nBut in this simple version we already trust our home server to handle login, sender identity, and routing. So for now that is enough.</p>\n<p>sequenceDiagram\nparticipant HS as Home Server\nparticipant ES as Someone Else&#39;s Server\nHS-&gt;&gt;HS: keep server signing private key\nHS-&gt;&gt;ES: send signed federation request\nES-&gt;&gt;HS: fetch discovery\nHS--&gt;&gt;ES: public signing key\nES-&gt;&gt;ES: verify signature using public key\nES-&gt;&gt;ES: process request if valid</p>\n<p>And that&#39;s the basic shape of federation:</p>\n<ol><li>Identity uses a domain.</li><li>Domain exposes discovery metadata.</li><li>Servers use discovery to find endpoints and public server keys.</li><li>Clients use recipient public keys to encrypt messages.</li><li>Servers use signing keys to authenticate federation requests.</li></ol>","headings":[{"level":1,"text":"How to Create Your Own Decentralized Messenger Protocol","id":"how-to-create-your-own-decentralized-messenger-protocol"},{"level":2,"text":"What is federation","id":"what-is-federation"},{"level":2,"text":"Federated Messenger Protocol","id":"federated-messenger-protocol"},{"level":2,"text":"User Identity","id":"user-identity"},{"level":2,"text":"Discovery","id":"discovery"},{"level":2,"text":"End to End","id":"end-to-end"},{"level":3,"text":"Resolving users","id":"resolving-users"},{"level":3,"text":"Publishing keys","id":"publishing-keys"},{"level":2,"text":"Messaging","id":"messaging"},{"level":2,"text":"So how to encrypt payload?","id":"so-how-to-encrypt-payload"},{"level":2,"text":"Signing server messages","id":"signing-server-messages"}]}}