first commit

README.md

@@ -0,0 +1,194 @@
+# PostfixAdmin-RS
+
+Rustowy panel administracyjny dla Postfix/Dovecot, rozwijany jako zamiennik runtime PHP PostfixAdmin i zgodny z jego istniejaca baza danych.
+
+Aktualna linia developerska: **0.0.1-dev**. Projekt jest przypiety do **Rust 1.99.1**, edition 2024. Frontend jest osadzony w pojedynczym binarnym pliku; bundlowanie assetow, sprite SVG i workflow developerski sa wzorowane na przekazanym RustBox. Stary wyglad PostfixAdmin nie jest kopiowany.
+
+## Development bez produkcyjnej bazy
+
+Domyslny `dev.sh` nie potrzebuje MySQL/PostgreSQL. Uzywa izolowanego SQLite w `.dev/postfixadmin-rs.sqlite` i przy pierwszym starcie tworzy mock schematu PostfixAdmin z danymi testowymi:
+
+```bash
+bash dev.sh
+```
+
+Konta testowe:
+
+```text
+admin@example.test         / admin123   # global-admin
+domain-admin@example.test  / domain123  # admin example.test
+user@example.test          / user123    # mailbox user
+```
+
+Reset mock DB oraz developerskiego mocka Rspamd DKIM:
+
+```bash
+POSTFIXADMIN_RS_DEV_RESET=1 bash dev.sh
+```
+
+`database.dev_mock=true` jest dozwolone tylko z `environment="development"` i backendem SQLite. Produkcyjna baza nie jest potrzebna do pracy nad UI/API.
+
+Jesli chcesz testowac bezposrednio na produkcyjnej bazie przez SSH, `dev.sh` moze zestawic lokalny tunnel. Domyslnie taka sesja jest **read-only**. Najprosciej skopiowac gotowy przyklad dla `host.linuxiarz.pl`:
+
+```bash
+cp .env.example .env
+$EDITOR .env
+bash dev.sh
+```
+
+W `.env` uzupelnij co najmniej `POSTFIXADMIN_RS_DEV_DB_PASSWORD`. Przyklad jest dopasowany do testowego hosta: `root@host.linuxiarz.pl:11922`, MySQL/MariaDB, baza `postfix`, uzytkownik DB `postfix` i lokalny port tunelu `13306`.
+
+Domyslny forward dla MySQL to `127.0.0.1:13306 -> 127.0.0.1:3306`, a dla PostgreSQL `127.0.0.1:15432 -> 127.0.0.1:5432`. Mozesz zmienic host/port po stronie serwera przez `POSTFIXADMIN_RS_DEV_DB_HOST` i `POSTFIXADMIN_RS_DEV_DB_PORT`. Weryfikacja host key SSH pozostaje wlaczona. Tunel uzywa `BatchMode=yes`, wiec przygotuj klucz/ssh-agent; opcjonalnie ustaw `POSTFIXADMIN_RS_SSH_IDENTITY` lub `POSTFIXADMIN_RS_SSH_KNOWN_HOSTS`.
+
+Zapisy na produkcyjnej bazie wymagaja dodatkowego, jawnego opt-in:
+
+```bash
+POSTFIXADMIN_RS_DEV_DB_MODE=ssh POSTFIXADMIN_RS_DEV_DB_WRITES=1 bash dev.sh
+```
+
+W tym trybie aplikacja moze modyfikowac realne skrzynki/aliasy. Do zwyklych testow UI i odczytu schematu nie ustawiaj `POSTFIXADMIN_RS_DEV_DB_WRITES=1`.
+
+## Co jest gotowe
+
+- logowanie admin/mailbox, sesje HttpOnly/SameSite, CSRF i rate limit,
+- global-admin, domain-admin i mailbox user,
+- domeny, skrzynki, aliasy, alias-domains i masowe usuwanie nieaktywnych forwardow,
+- limity domen, quota/domain quota, transport, backup MX i self-alias,
+- fetchmail, vacation/autoreply zgodny z tabela `vacation`, log, sendmail/broadcast i backup DB,
+- panel mailbox-user: wlasna quota/usage z DB, dane skrzynki, self-alias, bez odczytu IMAP,
+- opcjonalny ManageSieve dla mailbox-user: lista/edycja/walidacja/aktywacja skryptow filtrow, prosty wizualny builder reguly + edytor raw, bez IMAP,
+- admin preferences (m.in. domyslny cel aliasu),
+- DKIM keys/signing, TOTP, TOTP exceptions, application passwords,
+- Rspamd DKIM: generowanie kluczy, selector/path maps, configtest, podpinanie istniejacych kluczy i opcjonalny reload,
+- `smtp_active`, password expiration i DNS status, gdy schema je udostepnia,
+- bezpieczny natywny `maildir_template` zamiast PHP `maildir_name_hook`,
+- automatyczne subfoldery przez `doveadm mailbox create`, jesli lista jest skonfigurowana,
+- MySQL/MariaDB, PostgreSQL i SQLite przez SQLx Any,
+- hooki wykonywane jako program + argumenty, bez `sh -c`,
+- UI EN/PL z English jako domyslnym jezykiem; wybor z interfejsu jest zapamietywany w przegladarce, API pozostaje po angielsku.
+
+Pelna macierz: [COMPATIBILITY.md](COMPATIBILITY.md). Audyt 1:1 wobec dostarczonego PHP 4.0.1: [PORT-PARITY.md](PORT-PARITY.md).
+
+## Mailbox user, Vacation i ManageSieve
+
+Panel zwyklego uzytkownika nie pokazuje administracyjnej listy modulow ani cudzych skrzynek. Overview pobiera tylko rekord zalogowanej skrzynki i jej self-alias. Quota/usage pochodzi z tabel PostfixAdmin/Dovecot (`mailbox`, opcjonalnie `quota`/`quota2`); aplikacja nie loguje sie do IMAP, zeby zbudowac ten widok.
+
+Vacation pozostaje zgodny z PostfixAdmin: korzysta z tabeli `vacation` i ustawien `features.vacation` / `features.vacation_control`. Samo wlaczenie UI nie konfiguruje transportu/autorespondera po stronie Postfix/Dovecot, dlatego na istniejacym serwerze wlacz te flagi tylko wtedy, gdy mechanizm Vacation jest faktycznie skonfigurowany.
+
+ManageSieve jest dodatkiem niezaleznym od mechanizmu Vacation PA. Konfiguracja:
+
+```toml
+[sieve]
+enabled = true
+host = "127.0.0.1"
+port = 4190
+tls_mode = "starttls" # starttls | implicit | none
+allow_insecure_auth = false
+timeout_secs = 10
+read_only = false
+```
+
+Haslo mailbox-user jest przechowywane tylko w pamieci jego sesji, i tylko gdy Sieve jest wlaczone; nie trafia do JSON API ani logow. Po zmianie hasla credential sesji jest aktualizowany. Dla developerskiego testu przez SSH mozna wlaczyc drugi forward tym samym `dev.sh`:
+
+```bash
+POSTFIXADMIN_RS_DEV_SIEVE_ENABLED=true bash dev.sh
+```
+
+Domyslnie zewnetrzny ManageSieve przez dev tunnel jest read-only. Zapis wymaga osobnego `POSTFIXADMIN_RS_DEV_SIEVE_WRITES=1`; jest to niezalezne od `POSTFIXADMIN_RS_DEV_DB_WRITES`.
+
+## Hasla zgodne z PostfixAdmin
+
+Weryfikacja najpierw rozpoznaje format juz zapisany w rekordzie. Dzieki temu jedna baza moze zawierac stare i nowe hashe podczas migracji, bez masowego przepisywania kont.
+
+Obslugiwane sa m.in.:
+
+- `ARGON2ID`, `ARGON2ID.B64`, `ARGON2I`, `ARGON2I.B64`,
+- `BLF-CRYPT`, `BLF-CRYPT.B64`, `CRYPT`,
+- `SHA512-CRYPT`, `SHA512-CRYPT.B64`, legacy `SHA512.B64`, `SHA512`,
+- `SHA256-CRYPT`, `SHA256-CRYPT.B64`, `SHA256`,
+- `SHA1-CRYPT`, `SHA1`, `SHA1.B64`, `SHA`, `SSHA`,
+- `MD5-CRYPT`, legacy `md5crypt`, `PLAIN-MD5`, `MD5`, `MD5RAW`,
+- `AUTHLIB` (`md5raw`, `md5`, `SHA`, `crypt`),
+- `courier:md5`, `courier:md5raw`, `courier:sha1`, `courier:ssha`, `courier:sha256`,
+- `php_crypt:DES|MD5|BLOWFISH|SHA256|SHA512` z kompatybilnym difficulty/prefix,
+- `dovecot:METHOD` jako kontrolowany fallback do `doveadm pw`, bez shella i bez hasla w argv,
+- `PLAIN`, `CLEAR`, `cleartext` tylko dla zgodnosci/testow.
+
+Testy zawieraja referencyjne wektory z dostarczonego `tests/PacryptTest.php`. Slabe formaty pozostaja tylko dla kompatybilnosci; nowych kont nie nalezy na nie migrowac bez potrzeby.
+
+Dla przekazanego configu produkcyjnego pozostaje `php_crypt:MD5`, dopoki konfiguracja Dovecot/Postfix SASL nie zostanie zmieniona razem z panelem.
+
+## Konfiguracja przekazanego serwera
+
+`config.from-user.toml` odwzorowuje przekazany config PostfixAdmin, ale nie zawiera hasla bazy. Sekret podaj przez ENV:
+
+```bash
+export POSTFIXADMIN_RS_CONFIG="$PWD/config.from-user.toml"
+export POSTFIXADMIN_RS__DATABASE__PASSWORD='...'
+```
+
+## Jezyki interfejsu
+
+Frontend ma katalogi `src/web/i18n/en.json` i `src/web/i18n/pl.json`. `default_language = "en"` ustawia English jako pierwszy jezyk, a przelacznik w loginie i gornej belce zapisuje wybor w `localStorage`. Lokalizacja dotyczy tylko UI; endpointy, JSON i kody bledow API pozostaja angielskie.
+
+## Build / release gate
+
+```bash
+./scripts/build-release.sh
+```
+
+Gate wykonuje walidacje statyczna, `cargo fmt --check`, testy, Clippy z `-D warnings` i release build z `Cargo.lock`.
+
+## Migracja z PHP
+
+1. Zrob backup bazy i konfiguracji Postfix/Dovecot/PostfixAdmin.
+2. Najpierw testuj na kopii DB lub na mocku developerskim.
+3. Na realnej DB uruchom `--check-config`, sprawdz logowanie i CRUD na domenie testowej.
+4. Nie zmieniaj `password.scheme`, dopoki Dovecot/Postfix SASL nie obsluguje tego samego formatu.
+5. Reverse proxy przelacz dopiero po testach regresyjnych; PHP/FPM usun na koncu.
+
+## Status 0.0.1-dev
+
+To nadal wersja developerska, nie deklaruje jeszcze 100% parity PostfixAdmin 4.x. Pozostale luki to przede wszystkim webowy setup/upgrade schematu, XML-RPC, SMS provider, update checker oraz generic IMAP/Courier do tworzenia folderow. Dynamiczne hooki PHP (`*_struct_hook`, `language_hook`) nie beda uruchamiane jako PHP — wymagaja natywnego mechanizmu rozszerzen.
+
+W tym srodowisku nie ma `cargo`/`rustc`; proba pobrania toolchaina 1.99.1 jest dodatkowo blokowana przez brak DNS/network, wiec realny `cargo check/test/clippy` nie mogl zostac wykonany tutaj. Statyczny gate jest uruchamiany przed spakowaniem, ale developerski build trzeba ostatecznie zweryfikowac przez `bash dev.sh` na maszynie z Rust 1.99.1. Checklista testowa: [TESTING.md](TESTING.md).
+
+## Rspamd DKIM
+
+Integracja Rspamd nie rozbudowuje recznie `domain { ... }`. Uzywa map `selector_map` i `path_map`, generuje klucze przez `rspamadm`, wykonuje `rspamadm configtest` przed zaakceptowaniem zmian i moze wykonac jawnie skonfigurowany argv-only reload. Instrukcja: [docs/RSPAMD_DKIM.md](docs/RSPAMD_DKIM.md).
+
+### DKIM backends
+
+The UI exposes PostfixAdmin database DKIM and Rspamd DKIM as separate backends. They can be enabled independently:
+
+```toml
+[features]
+dkim = true
+
+[dkim]
+default_backend = "postfixadmin" # postfixadmin | rspamd
+
+[rspamd_dkim]
+enabled = true
+```
+
+When both are enabled, `dkim.default_backend` selects the tab opened first. Disabling one backend removes that tab from the UI.
+
+Mailbox users can optionally see DKIM as a **read-only DNS view** for their own domain (`[dkim].user_read_only = true`). The view merges only public records from the PostfixAdmin DKIM tables and Rspamd. `default_backend` is only a UI preference for administrators; there is no shared/global DKIM key in this project. Every key/selector remains associated with a concrete domain.
+
+When development uses the SSH database mode, `dev.sh` also forwards ManageSieve (`14190 -> 4190`) and, by default, builds a public-only Rspamd DKIM cache over SSH. The helper reads mapping/config metadata and derives the public key on the mail host; it never downloads private-key bytes. Disable this with `POSTFIXADMIN_RS_DEV_RSPAMD_PUBLIC_SYNC=false`.
+
+### Domain-focused UI
+
+`Domains` is the main entry point for domain administration. Clicking a domain opens a workspace with mailbox and alias usage, quota progress, mailboxes, aliases and alias-domain relationships. The standalone Mailboxes and Aliases pages show one domain at a time instead of rendering all domains at once.
+
+## Local Debian package
+
+For Debian-like systems, build a development `.deb` inside Docker:
+
+```bash
+./scripts/build-deb.sh
+```
+
+The builder uses Debian 12 as the compatibility baseline, installs the Rust toolchain pinned by `rust-toolchain.toml`, runs static validation, `cargo fmt --check`, tests and clippy, then writes the package and SHA256 file to `./packages/`. The resulting package installs the binary, a systemd service, `/etc/postfixadmin-rs/config.toml` and `/etc/default/postfixadmin-rs`. During installation it creates the unprivileged system user/group `postfixadmin`, runs the service as that identity, keeps `/etc/postfixadmin-rs` root-owned with group-read access for `postfixadmin`, and creates `/var/lib/postfixadmin-rs` for runtime state. It does not start the service automatically because database/Rspamd permissions must be configured first. Rspamd DKIM integration must be granted narrowly scoped write access to the configured key/map/config paths; do not run the whole service as root.
+