lyrathorpe/legacy-email-proxy

Fork 0

Files

T

Emma ThorpeandClaude Opus 5 fe540e1831

Build and publish container / build (pull_request) Successful in 7m8s

Details

feat: add Python packaging metadata and a Nix flake

Package the proxy properly so it can be consumed outside a container, and
without downstream users vendoring a package definition into their own
configuration.

- pyproject.toml: setuptools metadata with a `legacy-email-proxy` console
  script. Runtime dependencies are read dynamically from requirements.txt, so
  the Docker build and the package cannot drift apart.
- proxy_server.run(): a synchronous entry point for the console script, since
  `main` is a coroutine and cannot be referenced by one directly. The
  `__main__` path is unchanged in behaviour.
- package.nix / flake.nix: the package, an overlay, and a dev shell. The test
  suite runs as part of the build, so `nix flake check` covers it.
- module.nix: a NixOS module exposing `services.legacy-email-proxy` with
  freeform `settings` (environment variables) and a separate `environmentFile`
  for credentials, so secrets stay out of the Nix store. Runs under
  DynamicUser with CAP_NET_BIND_SERVICE only while a listener needs a
  privileged port, and opens no firewall ports.

The Dockerfile and its CI workflow are deliberately untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-21 13:05:34 +01:00

4.8 KiB

Raw Blame History

Legacy Email Proxy

Proxy an unauthenticated, unencrypted POP3 / SMTP server to authenticated IMAPS and SMTPS backends.

Features

Exposes legacy POP3 on 0.0.0.0:110 and legacy SMTP on 0.0.0.0:25
Forwards POP3 mailbox access to an IMAP backend
Forwards SMTP submissions to an SMTPS backend
Backend host, ports, and credentials are configured via environment variables

Environment Variables

POP3_BIND_ADDR (default 0.0.0.0)
POP3_BIND_PORT (default 110)
SMTP_BIND_ADDR (default 0.0.0.0)
SMTP_BIND_PORT (default 25)
BACKEND_IMAP_HOST
BACKEND_IMAP_PORT (default 993)
BACKEND_IMAP_USER
BACKEND_IMAP_PASS
BACKEND_IMAP_USE_SSL (default true)
BACKEND_IMAP_USE_STARTTLS (default false)
BACKEND_SMTP_HOST
BACKEND_SMTP_PORT (default 465)
BACKEND_SMTP_USER
BACKEND_SMTP_PASS
BACKEND_SMTP_USE_SSL (default true)
BACKEND_SMTP_USE_TLS (default false)
BACKEND_MUTATE (default false) - when true, POP3 deletions are propagated to the backend IMAP server (STORE +FLAGS / EXPUNGE). Default behaviour is to never mutate the backend mailbox on POP client deletions; the proxy only hides messages for the duration of the client session.

Build and run

This project targets the latest Python LTS release. The included Dockerfile uses python:3.12-slim, which is compatible with Python 3.12 and later LTS releases.

docker build -t legacy-email-proxy .
docker run --rm -p 110:110 -p 25:25 \
  -e BACKEND_IMAP_HOST=imap.example.com \
  -e BACKEND_IMAP_PORT=993 \
  -e BACKEND_IMAP_USER=imap-user \
  -e BACKEND_IMAP_PASS=imap-pass \
  -e BACKEND_SMTP_HOST=smtp.example.com \
  -e BACKEND_SMTP_PORT=465 \
  -e BACKEND_SMTP_USER=smtp-user \
  -e BACKEND_SMTP_PASS=smtp-pass \
  legacy-email-proxy

The project is also a standard Python package (pyproject.toml), so it installs without Docker. This puts a legacy-email-proxy command on PATH:

pip install .
legacy-email-proxy

requirements.txt remains the single source of runtime dependencies; pyproject.toml reads it, so the Docker build and the package cannot drift.

Nix

The repository is a flake. It exposes the package, an overlay, and a NixOS module.

nix run .#legacy-email-proxy   # run it
nix build .#legacy-email-proxy # build it; the test suite runs as part of the build
nix develop                    # dev shell with pytest

As a NixOS service, with the proxy's own flake as an input:

{
  inputs.legacy-email-proxy.url = "git+https://code.emmathe.dev/lyrathorpe/legacy-email-proxy";
  # optionally: inputs.legacy-email-proxy.inputs.nixpkgs.follows = "nixpkgs";
}

{
  imports = [ inputs.legacy-email-proxy.nixosModules.default ];

  services.legacy-email-proxy = {
    enable = true;
    settings = {
      POP3_BIND_ADDR = "10.0.0.1";
      SMTP_BIND_ADDR = "10.0.0.1";
      BACKEND_IMAP_HOST = "imap.example.com";
      BACKEND_IMAP_USER = "someone@example.com";
      BACKEND_SMTP_HOST = "smtp.example.com";
      BACKEND_SMTP_USER = "someone@example.com";
    };
    # Credentials belong here, not in `settings` -- anything in `settings`
    # lands in the world-readable Nix store.
    environmentFile = "/var/lib/legacy-email-proxy/backend.env";
  };
}

settings accepts any of the environment variables listed above; booleans and integers are converted for you. The service runs under DynamicUser, with CAP_NET_BIND_SERVICE granted only while a listener is on a privileged port. It opens no firewall ports — see "Security".

Prefer to manage the package yourself? overlays.default provides pkgs.legacy-email-proxy, and nixosModules.legacy-email-proxy is the same module without the package default wired to this flake.

Tests

Install development dependencies and run the test suite:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements-dev.txt
pytest -q

Notes

This implementation begins the proxy with a minimal POP3 command set and SMTP delivery path. It is designed to start development on the required application architecture.

Security

By design, the front-end POP3 (port 110) and SMTP (port 25) listeners are unencrypted and unauthenticated. Anyone who can reach port 110 obtains full mailbox access, and anyone who can reach port 25 can relay mail through the configured backend SMTP credentials, which is an open relay from the network's perspective.

Because of this, the listeners must be bound to a trusted internal network only, such as a private Docker bridge, a VPN interface, or localhost, and must not be exposed to untrusted networks or the public internet.

Operators who need to restrict the bind address can set POP3_BIND_ADDR / SMTP_BIND_ADDR to a specific internal interface instead of 0.0.0.0.

4.8 KiB Raw Blame History