Metadata-Version: 2.4
Name: eveo7-mumble-authenticator
Version: 3.0.0
Summary: AllianceAuth Authenticator for Mumble server with support for templinks
Keywords: eveonline,allianceauth,authenticator,mumble,templinks
Author: Aaron Kable, Adarnof, Ariel Rin, Basraah, Boris Talovikov, Eingang, Peter Pfeufer, Stefan Hacker
Author-email: Aaron Kable <aaronkable@gmail.com>, Adarnof <adarnof@gmail.com>, Ariel Rin <ozirascal@gmail.com>, Basraah <basraaheve@gmail.com>, Boris Talovikov <boris@talovikov.ru>, Eingang <eingang.vulpine@gmail.com>, Peter Pfeufer <info@ppfeufer.de>, Stefan Hacker <dd0t@users.sourceforge.net>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Communications :: Conferencing
Requires-Dist: zeroc-ice>=3.7.10.1,<3.8
Requires-Dist: passlib[bcrypt]>=1.7.4,<2.0.0
Requires-Dist: pymysql>=1.1.1,<2.0.0
Requires-Dist: diskcache>=5.6.3,<6.0.0
Requires-Dist: eveo7-mumbleserver-ice>=0.1.0,<1.0.0
Requires-Dist: prometheus-client>=0.22.1,<0.23.0
Requires-Dist: bcrypt<5
Requires-Dist: structlog>=24.0,<26.0
Requires-Dist: orjson>=3.10,<3.12
Requires-Dist: pydantic-settings>=2.5,<3.0
Requires-Dist: pluggy>=1.5,<2.0
Requires-Python: >=3.12, <3.13
Project-URL: homepage, https://gitlab.com/eveo7/eveo7-mumble-authenticator
Project-URL: Source, https://gitlab.com/eveo7/eveo7-mumble-authenticator
Project-URL: Issues, https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/issues
Description-Content-Type: text/markdown

# Alliance Auth Mumble Authenticator

[![Python](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/LICENSE)
[![Status](https://img.shields.io/badge/status-stable-brightgreen.svg)](https://gitlab.com/eveo7/eveo7-mumble-authenticator)

*Русская версия: [README.ru.md](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/README.ru.md).*

Bridges a Mumble (Murmur) ICE server to an Alliance Auth MariaDB backend,
with optional EVE Online templink guest access, EVE portrait textures,
Prometheus metrics, and a self-healing ICE healthcheck.

The authenticator runs as a single long-lived process. It connects to the
Murmur ICE interface, validates Mumble logins against the Alliance Auth
database (and, optionally, short-lived templink guest credentials), serves
avatars as channel textures, and parks idle users. Configuration is
supplied entirely through `MA__`-prefixed environment variables.

## Prerequisites

- **CPython 3.12, Linux `amd64` only.** `zeroc-ice` ships pre-built wheels
  for `cp312` on Linux only; Python 3.11 or 3.13 will not resolve.
- A reachable **Alliance Auth** MariaDB/MySQL database.
- A running **Murmur (Mumble) server** with the ICE interface enabled and
  its `Ice.Secret` known.
- **Docker** — only for the container install path.

## Install

A release `X.Y.Z` is published to both PyPI and Docker Hub on each tagged
release. The first release from this repository is pending; the commands
below apply once a release tag exists. Until then, install from source
([repository](https://gitlab.com/eveo7/eveo7-mumble-authenticator)) or
build the image locally (see [Docker usage](#docker-usage)).

PyPI:

```bash
pip install eveo7-mumble-authenticator
```

Docker Hub (`linux/amd64`):

```bash
docker pull docker.io/6run0/eveo7-mumble-authenticator:X.Y.Z
```

Pull a concrete release tag (`X.Y.Z`); `latest` tracks the newest release.

## Quick start

Configuration is read only from `MA__`-prefixed environment variables.
Create an `authenticator.env` file with the three required secrets and the
connection coordinates:

```bash
# Required — startup fails closed if any of these is unset.
MA__ALLIANCE_AUTH__DATABASE__PASSWORD=your-db-password
MA__ICE_SERVER__SECRET=your-murmur-ice-secret
MA__ICE_CLIENT__SECRET=your-murmur-ice-secret   # must equal ICE_SERVER__SECRET

# Point at your Alliance Auth database and Murmur ICE endpoint.
MA__ALLIANCE_AUTH__DATABASE__HOST=127.0.0.1
MA__ALLIANCE_AUTH__DATABASE__NAME=alliance_auth
MA__ALLIANCE_AUTH__DATABASE__USER=alliance
MA__ICE_SERVER__HOST=127.0.0.1
MA__ICE_SERVER__PORT=6502
```

Run it (installed from PyPI):

```bash
set -a; . ./authenticator.env; set +a
authenticator
```

Verify the console script responds (no configuration required for this):

```bash
authenticator --version
```

The complete set of variables, with every default and which ones are
required, lives in
[`example.env`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/example.env).

## Docker usage

```bash
docker run --rm \
  --env-file authenticator.env \
  -p 13004:13004 \
  -p 8000:8000 \
  -v "$(pwd)/data:/data" \
  docker.io/6run0/eveo7-mumble-authenticator:X.Y.Z
```

- **`13004`** — ICE callback adapter; **`8000`** — Prometheus metrics.
- **`/data`** — diskcache directory (avatar textures + the SELECT fallback
  cache). Persist it with a volume.
- The container runs as a non-root user (uid/gid `10000`).
- To expose metrics outside the container, add
  `MA__PROMETHEUS__HOST=0.0.0.0` to the env file — the endpoint binds
  loopback by default.

Build the image locally instead of pulling:

```bash
docker build -t eveo7-mumble-authenticator .
```

The build is multi-stage: by default it builds the wheel from this source
tree; pass `--build-arg WHEEL_FROM=pypi` to install the published release
instead. A reference Compose service is in
[`docker-compose.yml`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/docker-compose.yml).

### Networking caveat

Running the container attached to **multiple Docker networks** is
discouraged. The ICE callback adapter announces a single callback address
to Murmur; with several interfaces it may advertise the wrong one, and the
Mumble server then tries to reach an address that is unroutable from its
network. Prefer `network_mode: host` (set `MA__ICE_CLIENT__HOST` to the
reachable address), or attach a single network.

## Configuration

Variables mirror the nested settings tree: uppercase each key, join nested
keys with `__`, prefix everything with `MA__`, and index list entries
numerically. For example, a raw ICE property:

```bash
MA__ICE_PROPERTIES__LINES__0="Ice.ThreadPool.Server.Size = 5"
```

The most commonly set variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `MA__ALLIANCE_AUTH__DATABASE__HOST` | `127.0.0.1` | Alliance Auth MariaDB host |
| `MA__ALLIANCE_AUTH__DATABASE__NAME` | `alliance_auth` | Schema holding the Mumble tables |
| `MA__ALLIANCE_AUTH__DATABASE__USER` | `alliance` | Database user |
| `MA__ALLIANCE_AUTH__DATABASE__PASSWORD` | — *(required)* | Database password |
| `MA__ICE_SERVER__HOST` | `127.0.0.1` | Murmur ICE Meta host |
| `MA__ICE_SERVER__PORT` | `6502` | Murmur ICE Meta port |
| `MA__ICE_SERVER__SECRET` | — *(required)* | Shared ICE secret; empty disables the check |
| `MA__ICE_CLIENT__SECRET` | — *(required)* | Callback secret; must match the server secret |
| `MA__ALLIANCE_AUTH__AVATAR__ENABLED` | `true` | Serve EVE portraits as Mumble textures |
| `MA__IDLEHANDLER__ENABLED` | `false` | Move idle (AFK) users to a parking channel |
| `MA__PROMETHEUS__ENABLED` | `true` | Expose the Prometheus metrics endpoint |

Templink guest access is configured under `MA__GUEST_LINK__*`; it defaults
to the Alliance Auth database connection. YAML configuration files are no
longer accepted and cause an immediate startup error. The full reference,
generated from the settings schema, is
[`example.env`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/example.env).

## Limitations

- **Platform:** `linux/amd64`, CPython 3.12 only (pinned by the `zeroc-ice`
  wheel availability).
- **Configuration:** environment variables only — YAML and command-line
  configuration are rejected at startup.
- **Templinks:** the temporary guest password is carried in the
  `mumble://` URI in plaintext by design, so it cannot be stored hashed.
  Treat templinks as single-use, short-lived secrets. See
  [`docs/behavior-changes-v2.md`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/docs/behavior-changes-v2.md).

## Versioning

[Semantic Versioning](https://semver.org/). A release `X.Y.Z` is published
simultaneously to PyPI (`eveo7-mumble-authenticator==X.Y.Z`) and Docker Hub
(`docker.io/6run0/eveo7-mumble-authenticator:X.Y.Z`); the Docker `latest`
tag tracks the newest release.

## Documentation

- [`example.env`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/example.env) — full configuration reference.
- [`docs/operator-runbook.md`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/docs/operator-runbook.md) — capture sessions, baseline refreshes, snapshot workflow.
- [`docs/behavior-changes-v2.md`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/docs/behavior-changes-v2.md) — catalogue of observable behaviour contracts.
- [`CHANGELOG.md`](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/CHANGELOG.md) — release history.

## License

[GPL-3.0-or-later](https://gitlab.com/eveo7/eveo7-mumble-authenticator/-/blob/main/LICENSE).
A fork of the
[Alliance Auth Mumble authenticator](https://gitlab.com/allianceauth/mumble-authenticator),
extended with EVE Online templink guest support and an env-only,
protocol-based architecture.
