Skip to content

About

A Matrix homeserver in modern C++26 that applies OS-level containment and fail-closed engineering at every layer, not just input validation and TLS.

Topics

Resources

Code of conduct

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

584 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Merovingian

Latest release: latest · Documentation: omg-software.github.io/Merovingian

Note: Merovingian 1.0.0 is the first production release. Read its known limitations in CHANGELOG.md before you deploy it.

Build Static analysis Sanitizers Documentation CodeQL Quality Gate Status

Coverage CodeRabbit Pull Request Reviews

License: GPL-3.0-or-later C++26 Meson Code scanning

Table of contents

What is Merovingian and what makes it special?

Merovingian is a Matrix homeserver written in modern C++26, built around a single premise: a homeserver sits at the center of every deployment's federation identity, access tokens, and message metadata — and, for any room that isn't end-to-end encrypted, the plaintext of every conversation in it. It never holds the private keys clients use to encrypt E2EE rooms, and it never sees their plaintext — that stays client-side, by design of the Matrix protocol. But a compromised server can still forge federation traffic under its identity, mint or steal access tokens to impersonate users, read and exfiltrate every unencrypted room, and tamper with — or selectively withhold — the ciphertext of rooms it cannot read. Merovingian treats resisting that compromise as the product requirement, not a hardening pass applied after the protocol works.

Why choose Merovingian over other homeservers

Most homeservers are large, single-process applications where security is largely input validation and TLS. Merovingian goes further and applies operating-system-level containment and fail-closed engineering at every layer, so that compromising one part of the system doesn't hand an attacker the rest of it:

  • RAII ownership with mechanical checks. Naked new/delete and C allocation calls are rejected by the unsafe-pattern gate; dynamic ownership uses RAII, and shared ownership requires a reviewed justification. These restrictions and the test tools reduce risk; they do not prove C++ memory safety.
  • Process isolation with explicit shared boundaries. Thumbnail image decoding runs in a sandboxed child. When federation is enabled, the server starts federation workers and refuses startup if the proxy cannot be created. Main still verifies inbound request signatures, serves designated federation endpoints and handles defined transaction/room-snapshot fallback paths; workers relay mutations to main and read database snapshots. PostgreSQL supports a separate read-only worker role and an allowlist of hydrated tables; SQLite shares a read-only database file and hydrates broader data. Signing operations remain in main. See the architecture and database guides for the limits and platform-specific sandbox controls.
  • Fail-closed by default, not fail-open. Startup runs a hardening self-check that refuses to serve traffic unless seccomp, ASLR/PIE, RELRO, stack canaries, and capability bounding all report enabled. Federation signature verification, TLS validation, and config validation reject outright rather than silently degrading when something is missing or malformed.
  • Bounded secret storage and explicit lock requirements. New server signing secrets are encrypted at rest under the operator master key. The master key and derived 32-byte keys must obtain locked storage or are refused. Runtime signing-secret buffers are zeroised on release and attempt memory locking, but not every signing-key allocation checks lock success; an unconditional promise that every secret is always pinned would overstate the current implementation.
  • Cryptography is isolated and narrow. Reviewed libsodium-backed interfaces handle Matrix signatures, password hashing and token generation/hashing. New passwords use Argon2id and current token hashes use domain-separated keyed hashing; legacy token-hash formats remain accepted for lookup compatibility. TLS uses OpenSSL.
  • Constrained media processing. Uploads are checked against the configured MIME policy, remote fetches use the configured admission policy, and thumbnails are decoded in a sandboxed worker. Remote media is not universally quarantined: the supplied configuration allows remote fetches. Encrypted-room attachments remain ciphertext that the server cannot inspect as plaintext.
  • Structured logging and durable audit records. Logging supports token and event-content redaction; operators should keep the corresponding redaction settings enabled. Security-relevant actions such as logins, token invalidation, federation auth decisions and media quarantines have audit records. Redaction controls do not justify an unconditional promise that every possible log value is free of sensitive information.
  • Verification tooling accompanies the controls. The repository includes sanitizer, fuzzing, static-analysis, secret-scanning and release-artifact checks. Assess a particular revision or artifact from its completed job results and release evidence; the presence of a gate alone does not prove that it ran successfully.

These controls reduce the impact of hostile input and constrain sensitive operations. They do not establish memory safety or production readiness. For the boundaries and remaining limits, see docs/threat-model.md, docs/hardening.md, docs/crypto-boundary.md, and docs/security-coding-rules.md.

Merovingian has been in production since 1.0.0. Federation, persistence, packaging, and runtime security controls are implemented and covered by CI. 1.0.0 followed a release-gate security audit and was tagged without a green Complement run; the known limitations are listed in the 1.0.0 section of CHANGELOG.md.

Open work items, capability gaps, and milestone blockers live in docs/todos/: capability-gaps.md for per-area gaps and their status on the not-started → … → production-gated ladder, and production-milestone.md for the production milestone, including the Complement blocker that stays open after 1.0.0.

Why C++ and not Rust?

Rust's borrow checker gives a compile-time memory-safety guarantee that C++ doesn't have — that's a real gap, and this project doesn't pretend otherwise. The choice here is to close that gap through enforced discipline and continuous verification rather than to deny it exists:

  • Mechanical ownership checks reduce common mistakes. The unsafe-pattern gate rejects naked allocations and requires explicit review of shared ownership. RAII and smart pointers express resource lifetimes, but pattern checks cannot prove freedom from dangling references, bounds errors or data races.
  • The cryptographic boundary is explicit. Matrix cryptography goes through reviewed libsodium-backed interfaces. C-library integration requires careful ownership, input validation and secret handling in either C++ or Rust; using a C library does not remove the value of Rust’s guarantees elsewhere.
  • Platform reach. Merovingian packages for Linux, FreeBSD, NetBSD, and OpenBSD. C and C++ toolchains have been first-class on all of them for decades; Rust's standard library and crate ecosystem are comparatively thin on NetBSD and OpenBSD, where target support is lower-tier and breakage is more common.
  • Verification runs continuously. Sanitizers, parser fuzzing, static analysis and secret scanning complement review and behavior tests. They detect defects exercised by those tools; they do not replace compile-time memory-safety guarantees.

The language choice trades compile-time ownership guarantees for the project’s C++ toolchain and platform integration choices. The checks and containment controls above reduce risk without eliminating that tradeoff. See docs/security-coding-rules.md and docs/crypto-boundary.md for the enforced rules.

Release Artifact Verification

Every release artifact (tarball, package, and SHA256SUMS) is signed with a detached GPG .asc signature by the maintainer key. The public key fingerprint is:

66DFCC50187C8E46B5ED85FD92A3A264F0A7BE20

Verify a downloaded artifact before installing (substitute the release version for X.Y.Z):

gpg --keyserver keys.openpgp.org --recv-keys 66DFCC50187C8E46B5ED85FD92A3A264F0A7BE20
gpg --verify merovingian-X.Y.Z-linux-static-x86_64.tar.gz.asc \
             merovingian-X.Y.Z-linux-static-x86_64.tar.gz
sha256sum -c merovingian-X.Y.Z-linux-static-x86_64.tar.gz.sha256

Releases also carry SLSA provenance attestations (gh attestation verify, pinned to the workflow and tag that made the file), SPDX/CycloneDX SBOMs, and a machine-readable license summary. See docs/release-process.md and docs/user-manual.md for full details.

Installation and Configuration

Merovingian can be installed from a distro package, a portable static Linux tarball, or built from source. Full install steps (including the source build) live in docs/user-manual.md § Installation.

Substitute the release version for X.Y.Z in the commands below:

# Debian/Ubuntu example
sudo dpkg -i merovingian_X.Y.Z_amd64.deb

# Fedora example: use the RPM whose .fcNN tag matches `rpm -E %fedora`
sudo dnf install merovingian-X.Y.Z-1.fc44.x86_64.rpm

Merovingian is designed to sit behind a reverse proxy such as nginx, Apache httpd, Caddy, Traefik, or HAProxy. The proxy should own public TLS, while Merovingian stays bound to loopback listeners behind it. Worked examples for each proxy are in docs/user-manual.md § Reverse proxy.

Configuration lives in a single merovingian.conf file, validated at startup with fail-closed semantics — an unsafe listener bind, a missing secret file, or open registration without a token will refuse to start rather than boot insecurely. Start from the annotated example:

install -m 0644 config/merovingian.conf.example /etc/merovingian/merovingian.conf

The full parameter reference (server identity, CORS, TURN, listeners, database, registration, secrets, token lifetimes, encryption policy, federation policy, media, trust & safety, logging, rate limits) is documented in docs/user-manual.md § Configuration. Persistence backend behavior (SQLite for evaluation, PostgreSQL for production) is covered in docs/database-persistence.md.

Starting Merovingian for the first time

  1. Create the service user (distro packages do this automatically):
    groupadd -r merovingian
    useradd -r -g merovingian -d /var/lib/merovingian -s /sbin/nologin merovingian
  2. Copy and edit the example configuration, setting at minimum server.name, server.public_baseurl, and server.trusted_proxies.
  3. Generate the master key, which encrypts the Ed25519 signing secret at rest:
    (umask 077; openssl rand -out /etc/merovingian/master-key 32)
    chmod 0400 /etc/merovingian/master-key
    chown merovingian:merovingian /etc/merovingian/master-key
    Startup rejects a master key that is writable or readable by anyone but its owner.
  4. Configure the database — SQLite for a quick evaluation, PostgreSQL for anything else.
  5. Validate the configuration:
    merovingian-server --check-config /etc/merovingian/merovingian.conf
  6. Start the server:
    merovingian-server --config /etc/merovingian/merovingian.conf
    or, under systemd:
    systemctl enable --now merovingian.service
  7. Create the first admin account:
    merovingian-server --config /etc/merovingian/merovingian.conf \
      --bootstrap-admin alice \
      --bootstrap-admin-password-file /tmp/admin-pw
  8. Smoke test:
    curl -s http://127.0.0.1:8008/_matrix/client/versions
    Expect a JSON response listing supported Matrix client-server versions.

The full walkthrough, including CLI flags and systemd hardening details, is in docs/user-manual.md § Initial setup and § Running the server. Before opening a server to real users, work through the security checklist.

Upgrading Merovingian

  1. Review CHANGELOG.md for the target version.
  2. Stop the server.
  3. Back up the database and master key.
  4. Install the new package or tarball (see Release Artifact Verification).
  5. Validate the config with --check-config.
  6. Start the server.

Schema migrations are applied automatically on startup. See docs/user-manual.md § Upgrades for details, and docs/user-manual.md § Maintenance for backup guidance.

Troubleshooting

Symptom Likely cause Fix
duplicate configuration key at startup Two active database.backend lines or any other duplicate key. Remove the duplicate.
Config validation failure (exit 79) Unsafe listener bind, missing secret file, open registration without token, etc. Read the specific message and adjust merovingian.conf.
Client shows "Failed to connect" Proxy emits duplicate Access-Control-Allow-Origin headers, or /.well-known/matrix/client is missing/404. Remove proxy CORS headers; serve the well-known discovery file.
429 Too Many Requests for all clients server.trusted_proxies is unset behind a reverse proxy. Set server.trusted_proxies and ensure the proxy overwrites X-Forwarded-For with the direct peer IP.
502 send_join failed: timeout Large room join exceeds security.federation.join_timeout or the proxy's request timeout. Raise join_timeout and join_race_deadline; ensure they fit inside the proxy timeout.
502 send_join failed: response_too_large send_join response exceeds security.federation.join_response_max_size. Raise the value and restart both main and worker processes.
Federation worker does not start merovingian-fed-worker binary is missing or federation.worker.binary points to the wrong path. Check binary location and permissions.
Encrypted media downloads fail application/octet-stream was removed from security.media.allowed_mime_types. Restore it.

More detail and the full security checklist are in docs/user-manual.md § Troubleshooting.

Getting Started With Development

If you want to build or contribute to the project, start here:

Typical local setup starts with:

sh scripts/setup-dev-env.sh   # install toolchain and configure build dir
python build.py linux          # configure, compile, and test

build.py is the unified build entry point for all platforms. It delegates to the shell scripts in scripts/ and handles Meson setup, compilation, and testing in one step. See docs/dev-environment.md for platform-specific targets (linux, bsd, wsl), packaging commands (deb, rpm, pkg, static), and advanced options like build profiles and dry-run mode.

Sanitizer builds are supported through the unified CLI on every development target, including WSL. For example:

python build.py linux --builddir build-asan --buildtype debug --sanitize address,undefined
python build.py wsl --builddir build-tsan --buildtype debug --sanitize thread

About

A Matrix homeserver in modern C++26 that applies OS-level containment and fail-closed engineering at every layer, not just input validation and TLS.

Topics

Resources

Code of conduct

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages