feat: add Python packaging metadata and a Nix flake (#16)

## What

- `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 that console script; `main` is a coroutine and cannot be referenced by one. The `__main__` path behaves as before.
- `flake.nix` / `package.nix` — the package, `overlays.default`, a dev shell, and `checks`. The pytest suite runs as part of the build.
- `module.nix` — a NixOS module: `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`, takes `CAP_NET_BIND_SERVICE` only while a listener is on a privileged port, and opens no firewall ports.
- README: pip install, Nix usage, and a NixOS service example.

## Why

The proxy could only be consumed as a container. Anyone deploying it on NixOS had to vendor a package definition into their own configuration — which is exactly what happened downstream, and is now deleted there in favour of this.

## Not in scope

- The `Dockerfile` and its CI workflow are untouched.
- No Nix job in CI; the runner has no Nix. The build is reproducible locally with `nix flake check`.
- `version` is static and tracks the latest tag (`0.3.0`); bump it with the tag.

## Verification

- `nix flake check` — package builds, 14 tests pass inside the build.
- Consumed from a downstream NixOS host with `--override-input`: the unit's `ExecStart` resolves to the module's own build, and that flake's checks pass too.

---------

Co-authored-by: Emma Thorpe <emma.thorpe@citrix.com>
Reviewed-on: #16

module.nix

@@ -0,0 +1,129 @@
+# NixOS module for legacy-email-proxy.
+#
+# Consumed either through this flake's nixosModules.default (which defaults the
+# package to the flake's own build) or directly, alongside overlays.default.
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.services.legacy-email-proxy;
+
+  renderValue =
+    value:
+    if lib.isBool value then
+      lib.boolToString value # the proxy accepts 1/true/yes/on
+    else
+      toString value;
+
+  environment = lib.mapAttrs (_name: renderValue) (lib.filterAttrs (_: v: v != null) cfg.settings);
+
+  # The default listeners are 110 and 25, so the service normally needs
+  # CAP_NET_BIND_SERVICE. Drop it when both are configured above 1024.
+  portOf =
+    name: default:
+    let
+      value = cfg.settings.${name} or default;
+    in
+    if lib.isInt value then value else lib.toInt (toString value);
+
+  needsPrivilegedPorts = portOf "POP3_BIND_PORT" 110 < 1024 || portOf "SMTP_BIND_PORT" 25 < 1024;
+in
+{
+  options.services.legacy-email-proxy = {
+    enable = lib.mkEnableOption "the legacy POP3/SMTP proxy";
+
+    package = lib.mkPackageOption pkgs "legacy-email-proxy" { };
+
+    settings = lib.mkOption {
+      type =
+        with lib.types;
+        attrsOf (
+          nullOr (oneOf [
+            bool
+            int
+            str
+          ])
+        );
+      default = { };
+      example = lib.literalExpression ''
+        {
+          POP3_BIND_ADDR = "10.0.0.1";
+          BACKEND_IMAP_HOST = "imap.example.com";
+          BACKEND_IMAP_USER = "someone@example.com";
+          BACKEND_MUTATE = false;
+        }
+      '';
+      description = ''
+        Environment variables for the proxy, passed to the service as-is.
+        Booleans render as `true`/`false`, which the proxy accepts. The full
+        list of variables is in the project README.
+
+        Everything set here lands in the Nix store and is world-readable. Put
+        credentials in {option}`services.legacy-email-proxy.environmentFile`
+        instead.
+      '';
+    };
+
+    environmentFile = lib.mkOption {
+      type = lib.types.nullOr lib.types.path;
+      default = null;
+      example = "/var/lib/legacy-email-proxy/backend.env";
+      description = ''
+        Path to a systemd `EnvironmentFile` holding the backend credentials
+        (`BACKEND_IMAP_PASS`, `BACKEND_SMTP_PASS` and anything else that should
+        not be in the Nix store). Read by systemd at start, not by the service
+        user, so it can be root-owned and mode 0600.
+      '';
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    systemd.services.legacy-email-proxy = {
+      description = "Legacy POP3/SMTP proxy to authenticated IMAPS/SMTPS backends";
+      wantedBy = [ "multi-user.target" ];
+      after = [ "network.target" ];
+
+      environment = environment // {
+        PYTHONUNBUFFERED = "1";
+      };
+
+      serviceConfig = {
+        ExecStart = lib.getExe cfg.package;
+        Restart = "always";
+        RestartSec = 5;
+
+        DynamicUser = true;
+        AmbientCapabilities = lib.optional needsPrivilegedPorts "CAP_NET_BIND_SERVICE";
+        CapabilityBoundingSet = lib.optional needsPrivilegedPorts "CAP_NET_BIND_SERVICE";
+
+        NoNewPrivileges = true;
+        PrivateDevices = true;
+        PrivateTmp = true;
+        ProtectControlGroups = true;
+        ProtectHome = true;
+        ProtectKernelModules = true;
+        ProtectKernelTunables = true;
+        ProtectSystem = "strict";
+        # AF_NETLINK is not gratuitous: glibc's getaddrinfo opens a netlink
+        # socket to sort resolver results, and backends are reached by name.
+        RestrictAddressFamilies = [
+          "AF_INET"
+          "AF_INET6"
+          "AF_UNIX"
+          "AF_NETLINK"
+        ];
+        RestrictNamespaces = true;
+        RestrictRealtime = true;
+        RestrictSUIDSGID = true;
+        SystemCallArchitectures = "native";
+        SystemCallFilter = [ "@system-service" ];
+      }
+      // lib.optionalAttrs (cfg.environmentFile != null) {
+        EnvironmentFile = cfg.environmentFile;
+      };
+    };
+  };
+}