init

docs/development.md

@@ -0,0 +1,153 @@
+# Development Setup
+
+Lokales Setup für die Lab-Umgebung. Ziel: Tool gegen einen SoftHSM2-Container
+und eine Test-Sub-CA betreiben, ohne echte SMGW-Hardware.
+
+## Voraussetzungen
+
+- Rust ≥ 1.80 (`rustup`)
+- Docker / Podman
+- `xmlsec1` CLI (für die XML-DSig in `iconfig.sig`)
+- OpenSSL CLI (für Testzertifikate)
+
+Auf Debian/Ubuntu:
+
+```bash
+sudo apt install xmlsec1 libxmlsec1-dev openssl pkg-config
+```
+
+## Build & Run
+
+```bash
+cargo check
+cargo run
+```
+
+Logs via `RUST_LOG`:
+
+```bash
+RUST_LOG=smgw_pki_automator=debug,info cargo run
+```
+
+## SoftHSMv2 als Container
+
+`SoftHSMv2` per Docker laufen lassen. Beispiel (Pseudo-Compose, anpassen an
+euer Setup):
+
+```yaml
+services:
+  softhsm:
+    image: ghcr.io/example/softhsm2:latest
+    volumes:
+      - ./tokens:/var/lib/softhsm/tokens
+    environment:
+      SOFTHSM2_CONF: /etc/softhsm2.conf
+```
+
+Token einmalig initialisieren:
+
+```bash
+softhsm2-util --init-token --slot 0 \
+  --label "smgw-lab" \
+  --pin 1234 --so-pin 5678
+```
+
+Im `app.rs`-Boot-Pfad wird der Adapter konstruiert mit:
+
+```rust
+SoftHsmAdapter::new("/usr/lib/softhsm/libsofthsm2.so", "1234")
+```
+
+Pfad zur PKCS#11-Lib hängt vom Container/OS ab.
+
+## mTLS-Testzertifikate
+
+Für die Kommunikation mit der Test-Sub-CA brauchen wir:
+
+- **Client-Cert (EMT)** — wird im `reqwest`-Client als `Identity` geladen.
+- **Server-Cert der CA** — wird als Trust-Root im Client geladen.
+- **Eigenes Server-Cert** für den Axum-Callback-Endpunkt (mTLS-Server).
+- **CA-Trust** für eingehende CA-Calls, damit das Client-Cert der CA gegen
+  diesen Trust verifiziert werden kann.
+
+Test-PKI mit OpenSSL aufsetzen (vereinfacht):
+
+```bash
+mkdir -p certs && cd certs
+
+# Test-Root
+openssl req -x509 -newkey rsa:4096 -days 3650 -nodes \
+  -keyout test-root.key -out test-root.crt \
+  -subj "/CN=smgw-lab-root"
+
+# Client (EMT)
+openssl req -newkey rsa:4096 -nodes -keyout emt.key -out emt.csr \
+  -subj "/CN=emt-client"
+openssl x509 -req -in emt.csr -CA test-root.crt -CAkey test-root.key \
+  -CAcreateserial -out emt.crt -days 825
+
+# Server (CA-Mock + Axum-Callback)
+openssl req -newkey rsa:4096 -nodes -keyout server.key -out server.csr \
+  -subj "/CN=ca.test.local"
+openssl x509 -req -in server.csr -CA test-root.crt -CAkey test-root.key \
+  -CAcreateserial -out server.crt -days 825
+```
+
+PEM-Bundle für `reqwest::Identity::from_pem`:
+
+```bash
+cat emt.crt emt.key > emt-bundle.pem
+```
+
+## Datenbank
+
+SQLite, default `sqlite::memory:` im Stub-Boot. Für Persistenz Pfad setzen:
+
+```bash
+DATABASE_URL=sqlite://./data/smgw.db cargo run
+```
+
+Migrationen (sobald angelegt) via `sqlx`:
+
+```bash
+cargo install sqlx-cli --no-default-features --features sqlite,rustls
+sqlx migrate run
+```
+
+## SMTP
+
+Für lokales Testing `MailHog` oder `Mailpit`:
+
+```bash
+docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit
+```
+
+`SmtpAdapter::new("localhost", 1025)`.
+
+## Test-Sub-CA
+
+Optionen:
+
+1. **Mock-Server** mit `wiremock` für Integrationstests — antwortet auf
+   `RequestCertificate` mit `ok_syntax` und triggert anschließend einen
+   HTTP-Call gegen den eigenen Callback-Endpunkt. Kein BSI-Compliance-Ersatz,
+   aber gut für CI.
+2. **Echte Test-Sub-CA**-Instanz (sofern verfügbar) — Adresse + Test-EMT-
+   Zertifikate aus eurem Lab-Bestand einsetzen.
+
+## Tests
+
+```bash
+cargo test                    # Unit + In-Memory-Integration
+cargo test --features it      # Integration mit SoftHSM-Container (folgt)
+```
+
+Konvention: Tests liegen neben dem Code (`#[cfg(test)] mod tests`). Adapter-
+Tests, die externe Dienste brauchen, hinter Cargo-Feature `it` gaten.
+
+## Code-Style
+
+- `cargo fmt` vor jedem Commit.
+- `cargo clippy --all-targets -- -D warnings` muss grün sein.
+- Keine `Result<_, String>` in Produktionscode. Strukturierte Fehler via
+  `thiserror`.