Tuwunel Documentation

Tuwunel provides fine-grained control over user registration and authentication through several distinct mechanisms:

• Legacy Authentication: Includes password login, token-based invitations, guest access, and registration controls.
• OIDC Authorization Server: A built-in OAuth 2.0 / OpenID Connect server designed for next-generation Matrix clients. It manages refresh tokens, device grants, and account management by fronting identity providers.
• Identity Providers: Supports Single Sign-On (SSO) via upstream OAuth/OIDC providers like GitHub, Google, and Keycloak. These providers also serve as the human authentication step for the OIDC server.
• LDAP Delegation: Allows delegating user management and password authentication to an external LDAP directory.
• Enterprise JWT: Provides an operator-controlled signing key capable of minting tokens to authenticate as any user.

Tuwunel implements the Synapse administration API under the /_synapse/admin path. This compatibility allows existing Matrix administration tools (like synapse-admin, ketesa, Draupnir, and Meowlnir) to function with Tuwunel.

Important Notes:

• Authentication: Most endpoints require an administrator access token.
• Unimplemented Endpoints: If an endpoint is not supported, Tuwunel returns a 404 M_UNRECOGNIZED error.
• MAS (Matrix Authentication Service): Certain endpoints related to registration and password resets are not served when MAS is active.

When deploying Tuwunel, keep the following technical requirements in mind:

• Port 8448: While clients connect via port 443, other Matrix homeservers use port 8448 for federation. Both ports must be reachable.
• Minimal Container Images: Docker and Podman images contain only the binary, tini, and CA certificates. They do not include a shell. To inspect a running container, you must exec into it using the binary directly.
• Rootless Podman: If running rootless Podman, you must enable loginctl enable-linger to prevent containers from stopping when the user logs out.
• NixOS: Using the community services.matrix-conduit module requires manual workarounds for UNIX socket support and potential conflicts with jemalloc when using hardened profiles.

The Tuwunel delivery pipeline is organized into four sequential, gated phases. A failure in any phase prevents subsequent phases from executing, ensuring that only fully validated deliverables reach users.

Tuwunel implements the homeserver side of the Matrix Push Gateway API.

Clients register 'pushers' by providing their app's push gateway URL. Tuwunel then posts notifiable events to that URL. For standard hosted gateways, no server-side configuration is required.

Because hot reloading involves unloading and reloading code in memory, you must follow specific patterns to avoid memory corruption or crashing the server.

1. Manage Async Tasks and Lifetimes

Code is memory. You must ensure you do not attempt to execute code that has been unloaded.

• Never spawn a task without receiving and storing its JoinHandle.
• Always wait on join handles before leaving a scope or in another cleanup function called by an owning scope.

2. Use the correct Runtime Handle

Do not use tokio::spawn directly. Due to internal implementation details and potential bugs in how tokio handles thread-local variables in unsafe {} blocks, you must use the Tuwunel Handle defined in core/server.rs. This handle is typically accessible via the services() method or other state objects in the codebase.

Tuwunel provides three rolling tags that balance update frequency against stability:

• :latest: The most recent tagged release (updated ~monthly). Recommended for Production.
• :preview: Selected higher-confidence updates (updated ~weekly). Use this if you need fixes between official releases but want more stability than the development branch.
• :main: Every reviewed merge to the main branch (updated ~daily). Use this if you want to track development and accept the risk of unknown changes.

When a user authenticates via JWT for the first time:

• If register_user = true: Tuwunel creates a new account with the origin "jwt" and a placeholder password. The user can only re-authenticate using a valid JWT; the local password field is never used.
• If register_user = false: The login request fails with M_NOT_FOUND and no account is created.

Note: JWT only handles authentication. It does not synchronize admin status, group membership, or display names. For ongoing identity attribute synchronization, use LDAP or OIDC.

Tuwunel uses a provider layer to abstract media storage, supporting both the local filesystem and S3-compatible object storage.

Key concepts:

• media_storage_providers: A list of all active providers. Tuwunel reads media from all providers in this list. If a file is not found in the first provider, Tuwunel falls back to the next.
• store_media_on_providers: A list of providers where new uploads are written. If this list is empty, all providers in media_storage_providers receive new uploads.
• Implicit Provider: By default, Tuwunel uses an implicit provider named "media" which points to a media/ subdirectory inside your database_path on the local filesystem.

# Default behavior (implicit local storage)
media_storage_providers = ["media"]
store_media_on_providers = []

When using Docker, it is strongly advised to track the :latest tag for automatic updates.

Tagging Strategy:

• :latest: Stable release (recommended for production).
• :preview: Updates with higher confidence between major releases.
• :main: Most frequent updates (daily), reviewed but carries higher risk.