about

mesgd connects people, applications, and agents through messages. A sender describes what happened, and the programs interested in that message receive it. The sender does not need to know where those programs run, how many there are, or which language they use.

The service is written in Erlang and combines content-based routing over WebSocket with an HTTPS API for accounts, public keys, and access management. A listener describes its interests as a path, such as /kind=chat/room=lobby. Several programs can listen on the same path, so adding a logger or another agent does not require changing the sender.

Routing permissions determine which paths a grant allows a program to use. Public-key encryption determines who can read a payload, and signatures let a recipient verify who produced it. Those are separate decisions: an application can publish its public keys through mesgd while retaining the private keys needed to sign and decrypt.

Start with the local setup, or read the documentation for the account API, routing model, SDK, and Erlang agent.

setup

mesgd uses Erlang/OTP 25 or newer and beamer. From the server source, build the application, create its key identities, and start the local node:

make
make keys
make start
./mesgd status

Check the listener ports and certificate paths in mesgd.config before starting. The local example uses port 4433 for HTTPS and WebSocket and port 5544 for the management console. Clients need to trust the server certificate and verify its hostname.

Create an account with ./mesgd user add alice@example.com, or open /account on the HTTPS listener to sign up in the browser. The command generates and confirms the credentials, then writes private password, authenticator, QR, and recovery files in the current directory. Browser signup lets the person choose a password and enroll an authenticator themselves.

Administrator privileges come from the configured usernames, independently of the key files generated during setup. See Getting started for administrator enrollment, Configuration for persistent state and listener settings, and Command line for node operations.

routing

A listener path describes the contents of a message. For example, this message matches /kind=chat/room=lobby:

{"kind":"chat","room":"lobby","text":"hello"}

Use key=value for an exact field match or key=* when any value is acceptable. The message-access form can build a pattern from a sample by including, generalizing, or omitting each field. Permissions collect these patterns into named roles that can be assigned to users.

A grant token captures the assigned patterns for one hour. mesgd checks them against current assignments during authorization, so removing a permission takes effect on the next check; adding a permission requires a new token. A login session serves a different purpose: it establishes account identity, lasts 24 hours by default, and carries no path restrictions.

The current WebSocket listener accepts JSON text frames. A browser can authenticate with new WebSocket(url, ['json', token]); clients that support custom headers can send Authorization: Bearer TOKEN on the upgrade. Read Routing for matching and grant behavior and WebSocket for the connection format.

sdk

mesgd-sdk separates account operations from message cryptography. The auth client handles enrollment, login, recovery, public-key updates, and logout. The PKI library handles keys, signatures, and encryption, allowing an application to protect payloads without storing account credentials in its key file.

The intended application interface is small: send a message to a recipient, or register a callback for a sender. The SDK supplies the underlying pieces across eighteen languages, with different levels of HTTPS transport, PKI support, and test coverage. Check the language table for the implementation you plan to use.

from auth import AuthClient, https_transport

client = AuthClient(https_transport("https://mesgd.example.com"))
session = client.login("alice", password, otp_from_authenticator)
client.logout(session["access_token"])

Public signing and encryption keys can be published on an account so peers can verify signatures and encrypt payloads. A payload encrypted for a recipient remains private from mesgd when the service does not hold that recipient's private key. Routing fields must remain visible to the JSON router.

The encrypted ping/pong samples use a registration handshake that the current server does not implement. They demonstrate client cryptography rather than a working mesgd account connection. Start with SDK authentication for account integration, and read Samples before running those programs.

support

The launcher provides help for operating a node, managing accounts, and testing claim tokens:

mesgd help
mesgd user help
mesgd forge help
mesgd check help
mesgd otp help

For setup and operation, read the documentation. The HTTP reference describes request fields and responses, while Security explains the relationship between account sessions, administrator authority, routing grants, and payload encryption.

Source, issues, and patches are hosted in the mesgd and mesgd-sdk repositories.

contact