From 12ca56286bd668d7e344867deff74f86abf78e52 Mon Sep 17 00:00:00 2001
From: Gab <24553253+gabrix73@users.noreply.github.com>
Date: Fri, 17 Oct 2025 04:03:23 +0200
Subject: Revise README for YAMN Web Interface

Updated README.md to enhance documentation and security features.
---
 README.md | 801 +++++++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 502 insertions(+), 299 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 0743f46..3f21b25 100644
--- a/README.md
+++ b/README.md
@@ -1,71 +1,193 @@
-# 🔐 Guida Completa Installazione YAMN Web Interface
-
-## 📋 Indice
-1. [Prerequisiti](#prerequisiti)
-2. [Installazione Tor](#installazione-tor)
-3. [Installazione YAMN](#installazione-yamn)
-4. [Configurazione File Sicuri](#configurazione-file-sicuri)
-5. [Configurazione Nginx](#configurazione-nginx)
-6. [Configurazione PHP](#configurazione-php)
-7. [Configurazione Cronjob](#configurazione-cronjob)
-8. [Test Funzionalità](#test-funzionalità)
-9. [Troubleshooting](#troubleshooting)
+# YAMN Web Interface - Mix Network Email Gateway
+
+![Status](https://img.shields.io/badge/status-operational-green)
+![Security](https://img.shields.io/badge/security-hardened-red)
+![Tor](https://img.shields.io/badge/tor-mandatory-purple)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+A hardened web interface for [YAMN (Yet Another Mix Network)](https://github.com/crooks/yamn) implementing military-grade operational security with mandatory Tor routing and zero metadata retention.
+
+## 🎯 Mission Statement
+
+This interface provides access to the YAMN remailer network. **All traffic is mandatorily routed through Tor before reaching the YAMN network.** The YAMN entry node receives connections exclusively from Tor exit nodes, ensuring the true origin IP address is never exposed.
+
+### Double-Layer Unlinkability
+
+```
+User → Tor Network (3+ hops) → Tor Exit Node → YAMN Entry Remailer
+                                                 ↓
+                                          YAMN sees only Tor IP
+                                          User IP: UNKNOWN
+```
+
+- **Layer 1 (Tor):** Conceals identity from YAMN network
+- **Layer 2 (YAMN):** Multi-hop mixing (minimum 3 remailers) prevents recipient from tracing back to entry point
+
+**Result:** Complete unlinkability between sender and recipient.
 
 ---
 
-## 1. Prerequisiti
+## 🛡️ Security Features
+
+### Implemented Threat Mitigations
+
+| Threat | Mitigation | Implementation |
+|--------|------------|----------------|
+| **Traffic Analysis** | Padding + Cover traffic | Adaptive padding (512B-32KB) |
+| **Timing Attacks** | Randomized delays | 10-120s random intervals |
+| **Replay Attacks** | Message-ID cache | SQLite cache with 7-day expiration |
+| **Node Compromise** | Forward secrecy | Ephemeral keys per message |
+| **Size Correlation** | Adaptive padding | Standardized message sizes |
+| **Partial Network Observation** | Mixnet architecture | 3-hop minimum chain |
+| **Global Adversary** | Multi-hop routing | Tor + YAMN = 6+ total hops |
+| **Metadata Analysis** | No retention | Zero persistent logs |
+
+### Core Protection Principles
+
+- ✅ **Mandatory Tor Routing** - No exceptions, all traffic via Tor SOCKS5
+- ✅ **Zero Logging** - No access logs, no error logs, no metadata retention
+- ✅ **Military-Grade File Handling** - DoD 5220.22-M compliant deletion (3-pass overwrite)
+- ✅ **Replay Protection** - SHA256 message-ID cache with 7-day TTL
+- ✅ **Timing Obfuscation** - Random delays (10-120s) between operations
+- ✅ **Adaptive Padding** - Messages padded to standard sizes (512B, 1KB, 2KB, 4KB, 8KB, 16KB, 32KB)
+- ✅ **Input Validation** - All user input sanitized and validated
+- ✅ **Fortified Temporary Files** - Created in `/opt/yamn-data/pool/` with 0600 permissions
+- ✅ **Automatic Keyring Updates** - Downloads both stats and pubring.mix via Tor
+- ✅ **Multi-Source Redundancy** - 4 verified pinger sources with automatic fallback
 
-```bash
-# Sistema operativo supportato
-- Debian 11/12 o Ubuntu 20.04/22.04/24.04
+---
 
-# Software richiesto
-apt-get update
-apt-get install -y \
-    tor \
-    torsocks \
-    nginx \
-    php8.2-fpm \
-    php8.2-curl \
-    php8.2-sqlite3 \
-    php8.2-mbstring \
-    sqlite3 \
-    curl \
-    git
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        User Browser                         │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ HTTPS (TLS 1.3)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Nginx Web Server                         │
+│                  (No logging enabled)                       │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      PHP Frontend                           │
+│  • index.php (Form interface)                               │
+│  • send_email_with_tor.php (Message processing)             │
+│  • download_remailers.php (Auto-update)                     │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                ┌──────────┴──────────┐
+                │                     │
+                ▼                     ▼
+    ┌──────────────────┐  ┌──────────────────┐
+    │  Tor SOCKS5      │  │  torsocks        │
+    │  127.0.0.1:9050  │  │  wrapper         │
+    └────────┬─────────┘  └────────┬─────────┘
+             │                     │
+             ▼                     ▼
+    ┌──────────────────────────────────────┐
+    │       Tor Network (3+ hops)          │
+    └──────────────┬───────────────────────┘
+                   │
+                   ▼
+    ┌──────────────────────────────────────┐
+    │       Tor Exit Node                  │
+    │    (Only IP visible to YAMN)         │
+    └──────────────┬───────────────────────┘
+                   │
+                   ▼
+    ┌──────────────────────────────────────┐
+    │    YAMN Entry Remailer               │
+    │    (Receives from Tor IP only)       │
+    └──────────────┬───────────────────────┘
+                   │
+                   ▼
+           YAMN Network (3+ hops)
+                   │
+                   ▼
+              Recipient
 ```
 
 ---
 
-## 2. Installazione Tor
+## 📋 Requirements
+
+### System Requirements
+
+- **OS:** Debian 11/12 or Ubuntu 20.04/22.04/24.04
+- **RAM:** 512MB minimum, 1GB recommended
+- **Disk:** 1GB free space
+- **Network:** Internet connectivity required
+
+### Software Dependencies
 
-### A. Installare Tor
 ```bash
-apt-get install -y tor torsocks
+# Core components
+- Tor 0.4.7+ (anonymity network)
+- torsocks (Tor wrapper for applications)
+- YAMN (remailer client)
+- Nginx 1.18+ (web server)
+- PHP 8.1+ with extensions:
+  - php-fpm
+  - php-curl
+  - php-sqlite3
+  - php-mbstring
+
+# Build tools (for YAMN compilation)
+- Go 1.19+ (for building YAMN from source)
+- git
+```
+
+---
+
+## 🚀 Installation
+
+### Quick Start
+
+```bash
+# 1. Clone repository
+git clone https://github.com/gabrix73/yamnweb.git
+cd yamnweb
+
+# 2. Run installation script
+sudo ./install.sh
+
+# 3. Configure your domain in nginx
+sudo nano /etc/nginx/sites-available/yamnweb
+
+# 4. Test installation
+sudo -u www-data php test_download.php
 ```
 
-### B. Configurare Tor
+### Manual Installation
+
+#### Step 1: Install Tor
+
 ```bash
-# Backup configurazione originale
-cp /etc/tor/torrc /etc/tor/torrc.backup
+# Install Tor and torsocks
+apt-get update
+apt-get install -y tor torsocks
 
-# Creare nuova configurazione
+# Configure Tor
 cat > /etc/tor/torrc << 'EOF'
-# SOCKS proxy con stream isolation
+# SOCKS proxy with stream isolation
 SocksPort 127.0.0.1:9050 IsolateDestAddr IsolateDestPort
 SocksPort 127.0.0.1:9150 IsolateDestAddr IsolateDestPort
 
-# Control port per gestione circuiti
+# Control port for circuit management
 ControlPort 127.0.0.1:9051
 CookieAuthentication 1
 CookieAuthFileGroupReadable 1
 
-# Ottimizzazione circuiti
+# Circuit optimization
 CircuitBuildTimeout 60
 LearnCircuitBuildTimeout 0
 MaxCircuitDirtiness 600
 NewCircuitPeriod 30
 
-# Stream isolation avanzata
+# Advanced stream isolation
 IsolateClientAddr 1
 IsolateSOCKSAuth 1
 IsolateClientProtocol 1
@@ -73,80 +195,42 @@ IsolateClientProtocol 1
 # Security
 SafeLogging 1
 WarnUnsafeSocks 1
-
-# Performance
-NumEntryGuards 8
-NumDirectoryGuards 3
-
-# Opzionale: Escludere nodi exit in certi paesi
-# ExcludeExitNodes {us},{gb},{au},{ca},{nz}
-# StrictNodes 0
 EOF
-```
 
-### C. Avviare Tor
-```bash
+# Start Tor
 systemctl enable tor
 systemctl restart tor
 systemctl status tor
 
-# Verificare che sia in ascolto
+# Verify Tor is running
 netstat -tlnp | grep tor
-# Dovresti vedere:
-# 127.0.0.1:9050 (SOCKS)
-# 127.0.0.1:9051 (Control)
+# Should show: 127.0.0.1:9050 (SOCKS) and 127.0.0.1:9051 (Control)
 ```
 
-### D. Testare Tor
-```bash
-# Test 1: Connessione SOCKS
-curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
+#### Step 2: Install YAMN
 
-# Dovrebbe mostrare: "IsTor":true
-
-# Test 2: Con torsocks
-torsocks curl https://check.torproject.org/api/ip
-```
-
----
-
-## 3. Installazione YAMN
-
-### A. Scaricare e compilare YAMN
 ```bash
-# Creare directory
+# Install Go compiler
+apt-get install -y golang-go
+
+# Download and build YAMN
 mkdir -p /opt/yamn-build
 cd /opt/yamn-build
-
-# Scaricare sorgenti
 wget https://github.com/crooks/yamn/archive/refs/heads/master.zip
 unzip master.zip
 cd yamn-master
-
-# Installare Go se necessario
-apt-get install -y golang-go
-
-# Compilare
 go build
 
-# Copiare binario
+# Install YAMN
 mkdir -p /opt/yamn-master
 cp yamn /opt/yamn-master/
 chmod +x /opt/yamn-master/yamn
 
-# Verificare
-/opt/yamn-master/yamn --version
-```
-
-### B. Configurare YAMN
-```bash
-# Creare configurazione
+# Create configuration
 cat > /opt/yamn-master/yamn.yml << 'EOF'
-# YAMN Configuration
-
 remailer:
-  name: "your-remailer"           # Cambia con il tuo nome
-  address: "yamn@yourdomain.com"  # Cambia con la tua email
+  name: "your-remailer"
+  address: "yamn@yourdomain.com"
 
 files:
   pubring: "pubring.mix"
@@ -163,229 +247,153 @@ mail:
   outfile: no
   sendmail: yes
   smtprelay: "localhost:25"
-  # Se usi autenticazione SMTP:
-  # smtpusername: "your-user"
-  # smtppassword: "your-pass"
 
 stats:
   numcopies: 2
 
-# Client mode settings
 chain:
   length: 3
   select: "*,*,*"
 EOF
 
-# Creare directory necessarie
+# Create required directories
 mkdir -p /opt/yamn-master/{pool,Maildir/{cur,new,tmp},chunkdb}
 chmod 700 /opt/yamn-master/{pool,Maildir,chunkdb}
 ```
 
----
-
-## 4. Configurazione File Sicuri
+#### Step 3: Install Web Interface
 
-### A. Creare directory sicure
 ```bash
-# Directory per dati sensibili (fuori da web root!)
+# Create protected directories
 mkdir -p /opt/yamn-data/{pool,cache,backups}
 chmod 700 /opt/yamn-data
 chown www-data:www-data /opt/yamn-data -R
 
-# Directory web
+# Install web files
 mkdir -p /var/www/yamnweb
 cd /var/www/yamnweb
-```
 
-### B. Copiare file sicuri
-```bash
-# Copiare i file PHP sicuri che hai ricevuto:
-# - downloadRemailers_secure.php
-# - tor_extension_secure.php
-# - send_secure.php
-# - index.php (interfaccia)
-# - styles.css
-
-# Impostare permessi
+# Copy application files
+# - index.php
+# - send_email_with_tor.php
+# - download_remailers.php
+# - tor_extension.php
+# - test_download.php
+# - cron_update.sh
+
+# Set permissions
 chown www-data:www-data /var/www/yamnweb -R
 chmod 755 /var/www/yamnweb
 chmod 644 /var/www/yamnweb/*.php
-chmod 644 /var/www/yamnweb/*.css
+chmod 755 /var/www/yamnweb/*.sh
 
-# RIMUOVERE file log vecchi se presenti
-rm -f /var/www/yamnweb/*.log
-rm -f /var/www/yamnweb/*.txt
-```
-
-### C. Permettere a www-data di usare Tor
-```bash
+# Allow www-data to use Tor
 usermod -a -G debian-tor www-data
 ```
 
----
+#### Step 4: Configure Nginx
 
-## 5. Configurazione Nginx
-
-### A. Creare configurazione sito
 ```bash
 cat > /etc/nginx/sites-available/yamnweb << 'EOF'
 server {
     listen 80;
-    server_name your-domain.com;  # Cambia con il tuo dominio
-    
-    # Redirect to HTTPS
+    server_name your-domain.com;
     return 301 https://$server_name$request_uri;
 }
 
 server {
     listen 443 ssl http2;
-    server_name your-domain.com;  # Cambia con il tuo dominio
+    server_name your-domain.com;
     
     # TLS 1.3 only
     ssl_protocols TLSv1.3;
     ssl_ciphers 'TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384';
     ssl_prefer_server_ciphers on;
     
-    # SSL certificates (usa Let's Encrypt o certificati esistenti)
+    # SSL certificates
     ssl_certificate /etc/ssl/certs/your-cert.pem;
     ssl_certificate_key /etc/ssl/private/your-key.pem;
     
     # HSTS
-    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header Strict-Transport-Security "max-age=31536000" always;
     
-    # NO LOGS - CRITICO!
+    # CRITICAL: NO LOGS
     access_log off;
     error_log /dev/null;
     
     # Security headers
     add_header X-Frame-Options "DENY" always;
     add_header X-Content-Type-Options "nosniff" always;
-    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline';" always;
+    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none';" always;
     add_header Referrer-Policy "no-referrer" always;
-    add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;
     
     # Rate limiting
     limit_req_zone $binary_remote_addr zone=yamnlimit:10m rate=10r/m;
     limit_req zone=yamnlimit burst=5 nodelay;
     
     root /var/www/yamnweb;
-    index index.php index.html;
+    index index.php;
     
-    # PHP processing
     location ~ \.php$ {
         include snippets/fastcgi-php.conf;
         fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
-        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
-        include fastcgi_params;
-        
-        # Hide PHP version
         fastcgi_hide_header X-Powered-By;
     }
     
-    # Block access to sensitive files
     location ~ /\.(ht|git|env|log|txt|bak|tmp)$ {
         deny all;
     }
-    
-    # Block access to secure directories
-    location ~ ^/(pool|cache|backups|opt)/ {
-        deny all;
-    }
-    
-    # Disable autoindex
-    autoindex off;
 }
 EOF
 
-# Abilitare sito
+# Enable site
 ln -s /etc/nginx/sites-available/yamnweb /etc/nginx/sites-enabled/
 rm -f /etc/nginx/sites-enabled/default
 
-# Test configurazione
+# Test and restart
 nginx -t
-
-# Riavviare Nginx
 systemctl restart nginx
 ```
 
----
-
-## 6. Configurazione PHP
+#### Step 5: Configure Automatic Updates
 
-### A. Configurare PHP-FPM
 ```bash
-# Modificare /etc/php/8.2/fpm/php.ini
+# Make cron script executable
+chmod +x /var/www/yamnweb/cron_update.sh
 
-cat >> /etc/php/8.2/fpm/php.ini << 'EOF'
-
-; Security settings
-display_errors = Off
-display_startup_errors = Off
-log_errors = Off
-error_log = /dev/null
-
-; Session security
-session.use_cookies = 0
-session.use_trans_sid = 0
-session.cookie_httponly = 1
-session.cookie_secure = 1
-session.cookie_samesite = Strict
-
-; File uploads
-file_uploads = Off
-upload_max_filesize = 0M
-
-; Execution limits
-max_execution_time = 300
-memory_limit = 256M
-
-; Extensions
-extension=curl
-extension=sqlite3
-extension=mbstring
-EOF
+# Add to crontab
+crontab -u www-data -e
 
-# Riavviare PHP-FPM
-systemctl restart php8.2-fpm
+# Add this line:
+*/6 * * * * /var/www/yamnweb/cron_update.sh
 ```
 
 ---
 
-## 7. Configurazione Cronjob
+## 🧪 Testing
+
+### Test 1: Verify Tor Connection
 
-### A. Installare script cron
 ```bash
-# Copiare script cron
-cp cron_update_remailers.sh /var/www/yamnweb/
-chmod +x /var/www/yamnweb/cron_update_remailers.sh
-chown www-data:www-data /var/www/yamnweb/cron_update_remailers.sh
+# Test Tor SOCKS proxy
+curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
 
-# Aggiungere a crontab di www-data
-crontab -u www-data -e
+# Expected output: {"IsTor":true, ...}
 
-# Aggiungere questa riga:
-*/6 * * * * /var/www/yamnweb/cron_update_remailers.sh
-```
+# Test with torsocks
+torsocks curl https://check.torproject.org/api/ip
 
-### B. Creare log file
-```bash
-touch /var/log/yamn_cron.log
-touch /var/log/yamn_download.log
-chown www-data:www-data /var/log/yamn_*.log
-chmod 600 /var/log/yamn_*.log
+# Expected output: {"IsTor":true, ...}
 ```
 
----
+### Test 2: Test Remailer Download
 
-## 8. Test Funzionalità
-
-### A. Test manuale download
 ```bash
-# Eseguire come www-data
-sudo -u www-data php /var/www/yamnweb/test_remailer_download.php
+# Run as www-data user
+sudo -u www-data php /var/www/yamnweb/test_download.php
 ```
 
-Output atteso:
+**Expected output:**
 ```
 === YAMN Secure Downloader Test ===
 
@@ -404,9 +412,10 @@ Output atteso:
 ✅ All checks passed! YAMN is ready to use.
 ```
 
-### B. Test invio email
+### Test 3: Test YAMN Sending
+
 ```bash
-# Creare messaggio di test
+# Create test message
 cat > /tmp/test_message.txt << 'EOF'
 From: anonymous@anonymous.invalid
 To: your-test-email@example.com
@@ -415,143 +424,337 @@ Subject: YAMN Test Message
 This is a test message sent through YAMN.
 EOF
 
-# Inviare con yamn
+# Send via YAMN with Tor
 cd /opt/yamn-master
 torsocks ./yamn --mail --chain="*,*,*" --copies=1 < /tmp/test_message.txt
 
-# Controllare pool
+# Check pool directory
 ls -la /opt/yamn-master/pool/
 ```
 
-### C. Test interfaccia web
-```bash
-# Aprire browser e navigare a:
-https://your-domain.com
-
-# Compilare form e inviare email di test
-# Verificare che:
-# 1. Form viene validato correttamente
-# 2. Email viene aggiunta al pool
-# 3. Nessun errore nei log
+### Test 4: Test Web Interface
+
+1. Open browser: `https://your-domain.com`
+2. Fill out the form with test data
+3. Submit message
+4. Verify success message appears
+5. Check no errors in system logs
+
+---
+
+## 🔧 Configuration
+
+### Tor Configuration
+
+Edit `/etc/tor/torrc`:
+
+```ini
+# Optional: Exclude certain countries from exit nodes
+# ExcludeExitNodes {us},{gb},{au},{ca},{nz}
+# StrictNodes 0
+
+# Performance tuning
+NumEntryGuards 8
+NumDirectoryGuards 3
+```
+
+### YAMN Configuration
+
+Edit `/opt/yamn-master/yamn.yml`:
+
+```yaml
+# Customize remailer settings
+remailer:
+  name: "your-remailer-name"
+  address: "yamn@your-domain.com"
+
+# SMTP settings (if using authenticated SMTP)
+mail:
+  sendmail: yes
+  smtprelay: "smtp.example.com:587"
+  smtpusername: "your-username"
+  smtppassword: "your-password"
+```
+
+### PHP Configuration
+
+Edit `/etc/php/8.2/fpm/php.ini`:
+
+```ini
+# Security settings
+display_errors = Off
+log_errors = Off
+error_log = /dev/null
+
+# Resource limits
+max_execution_time = 300
+memory_limit = 256M
+
+# Disable file uploads (security)
+file_uploads = Off
+```
+
+---
+
+## 🔍 How It Works
+
+### Message Flow
+
+1. **User submits message** via web form (HTTPS)
+2. **PHP validates input** and checks for replays (SHA256 message-ID)
+3. **Adaptive padding applied** to standardize message size
+4. **Random delay** (10-120 seconds) prevents timing correlation
+5. **Protected temporary file** created in `/opt/yamn-data/pool/` with 0600 permissions
+6. **torsocks wrapper** called: `torsocks yamn --mail --chain="*,*,*" ...`
+7. **All YAMN connections** automatically routed through Tor SOCKS5 (127.0.0.1:9050)
+8. **YAMN receives** connection from Tor exit node IP (user IP unknown)
+9. **Message encrypted** and sent through 3+ YAMN remailers
+10. **Temporary file** wiped (DoD 5220.22-M: 3-pass overwrite)
+11. **Message-ID stored** in replay cache (SQLite, 7-day TTL)
+
+### Tor Routing Implementation
+
+#### For Remailer List Downloads
+
+**File:** `download_remailers.php`
+
+```php
+// cURL configured with Tor SOCKS5 proxy
+curl_setopt_array($ch, [
+    CURLOPT_PROXY => '127.0.0.1:9050',          // Tor SOCKS proxy
+    CURLOPT_PROXYTYPE => CURLPROXY_SOCKS5_HOSTNAME, // DNS via Tor
+    // ...
+]);
 ```
 
+#### For YAMN Message Sending
+
+**File:** `tor_extension.php`
+
+```php
+// torsocks wrapper forces all connections through Tor
+$command = sprintf(
+    'torsocks %s --mail --chain=%s --copies=%d < %s',
+    '/opt/yamn-master/yamn',
+    $chain,
+    $copies,
+    $messageFile
+);
+```
+
+**How torsocks works:**
+- Uses `LD_PRELOAD` to intercept syscalls
+- Redirects `connect()` to Tor SOCKS5
+- Resolves DNS through Tor (prevents leaks)
+- Transparent to application (YAMN thinks it's connecting normally)
+
 ---
 
-## 9. Troubleshooting
+## 📊 File Structure
 
-### Problema: "Tor is not available"
+```
+/var/www/yamnweb/
+├── index.php                      # Main web interface
+├── send_email_with_tor.php        # Message processing
+├── download_remailers.php         # Auto-update remailer lists
+├── tor_extension.php              # Tor routing & YAMN interface
+├── test_download.php              # Testing utility
+└── cron_update.sh                 # Cronjob script
+
+/opt/yamn-master/
+├── yamn                           # YAMN binary
+├── yamn.yml                       # YAMN configuration
+├── pubring.mix                    # Public keyring (auto-updated)
+├── pool/                          # Outgoing message queue
+├── Maildir/                       # Incoming mail (if running as server)
+└── chunkdb/                       # Partial message reassembly
+
+/opt/yamn-data/
+├── pool/                          # Secure temp files
+├── cache/
+│   ├── remailers.txt             # Downloaded stats
+│   └── replay_cache.db           # SQLite replay protection
+└── backups/                       # Automatic backups
+    ├── remailers_*.bak
+    └── pubring_*.bak
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Problem: "Tor is not available"
+
+**Diagnosis:**
 ```bash
-# Verificare stato Tor
 systemctl status tor
-
-# Verificare porte in ascolto
 netstat -tlnp | grep tor
-
-# Test connessione
 curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
+```
 
-# Se non funziona, riavviare Tor
+**Solution:**
+```bash
 systemctl restart tor
+journalctl -u tor -f
 ```
 
-### Problema: "Permission denied" su file
+### Problem: "Failed to download from all sources"
+
+**Diagnosis:**
 ```bash
-# Verificare proprietà
-ls -la /opt/yamn-data/
-ls -la /opt/yamn-master/
+# Test manual download via Tor
+torsocks curl https://echolot.virebent.art/mlist2.txt
 
-# Correggere permessi
-chown www-data:www-data /opt/yamn-data -R
-chmod 700 /opt/yamn-data
-chmod 700 /opt/yamn-master/pool
+# Check Tor logs
+journalctl -u tor --since "10 minutes ago"
 ```
 
-### Problema: "Failed to download from all sources"
+**Solution:**
 ```bash
-# Test manuale connessione
-torsocks curl https://echolot.virebent.art/mlist2.txt
-
-# Verificare proxy Tor
-ps aux | grep tor
+# Restart Tor
+systemctl restart tor
 
-# Verificare configurazione PHP cURL
-php -i | grep -i curl
+# Request new circuit
+sudo -u debian-tor tor-control --signal NEWNYM
 ```
 
-### Problema: YAMN non invia messaggi
+### Problem: "Permission denied" on files
+
+**Solution:**
 ```bash
-# Verificare configurazione YAMN
-cat /opt/yamn-master/yamn.yml
+# Fix ownership
+chown www-data:www-data /opt/yamn-data -R
+chmod 700 /opt/yamn-data
 
-# Test manuale
+# Fix YAMN permissions
+chmod 700 /opt/yamn-master/pool
+chmod 700 /opt/yamn-master/Maildir
+```
+
+### Problem: Messages not sending
+
+**Diagnosis:**
+```bash
+# Test YAMN manually
 cd /opt/yamn-master
-echo "Test" | ./yamn --mail --to test@example.com --stdout
+echo "Test" | torsocks ./yamn --mail --to test@example.com --stdout
 
-# Verificare pool
+# Check pool
 ls -la /opt/yamn-master/pool/
 
-# Verificare pubring
+# Verify pubring.mix exists
 ls -la /opt/yamn-master/pubring.mix
 ```
 
-### Log utili
+**Solution:**
 ```bash
-# Log nginx (se abilitati temporaneamente)
-tail -f /var/log/nginx/error.log
+# Force pubring download
+sudo -u www-data php -r "
+require 'download_remailers.php';
+\$d = new SecureRemailerDownloader();
+\$d->forceUpdate();
+"
+```
 
-# Log PHP
-tail -f /var/log/php8.2-fpm.log
+### Useful Logs
 
-# Log Tor
+```bash
+# Tor logs
 journalctl -u tor -f
 
-# Log cron
+# Nginx logs (if temporarily enabled)
+tail -f /var/log/nginx/error.log
+
+# PHP logs
+tail -f /var/log/php8.2-fpm.log
+
+# Cron logs
 tail -f /var/log/yamn_cron.log
 ```
 
 ---
 
-## 🎯 Checklist Finale
-
-- [ ] Tor installato e funzionante
-- [ ] YAMN compilato e configurato
-- [ ] Directory sicure create (/opt/yamn-data/)
-- [ ] Nginx configurato senza logging
-- [ ] PHP configurato correttamente
-- [ ] File PHP sicuri installati
-- [ ] Cronjob configurato
-- [ ] Test download completato con successo
-- [ ] Test invio email funzionante
-- [ ] Interfaccia web accessibile
-- [ ] Nessun file .log in /var/www/yamnweb/
-- [ ] Permessi corretti su tutti i file
+## 🔒 Security Checklist
+
+- [ ] Tor installed and running
+- [ ] torsocks installed and functional
+- [ ] YAMN compiled and configured
+- [ ] Secure directories created (`/opt/yamn-data/`)
+- [ ] Nginx configured **without logging** (`access_log off; error_log /dev/null;`)
+- [ ] PHP configured to not display errors
+- [ ] All web files owned by `www-data`
+- [ ] Cronjob configured for automatic updates
+- [ ] Test download completed successfully
+- [ ] Test message sent successfully
+- [ ] **No `.log` files in `/var/www/yamnweb/`**
+- [ ] Permissions correct (0700 for sensitive dirs, 0600 for sensitive files)
+- [ ] TLS 1.3 enabled with strong ciphers
+- [ ] Rate limiting active
+- [ ] Security headers configured
+- [ ] Replay protection tested
+- [ ] Timing delays verified
+
+---
+
+## 📚 References
+
+- **YAMN Project:** https://github.com/crooks/yamn
+- **YAMN Documentation:** https://mixmin.net/yamn.html
+- **Tor Project:** https://www.torproject.org/
+- **Mixmaster Protocol:** http://mixmaster.sourceforge.net/
+- **Victor's YAMN Pinger:** https://echolot.virebent.art/
+- **Remailer Best Practices:** https://www.freehaven.net/anonbib/
+
+---
+
+## ⚠️ Disclaimer
+
+This software is provided for legitimate privacy protection purposes. Users are responsible for complying with all applicable laws and regulations in their jurisdiction. The authors assume no liability for misuse.
+
+**Important:**
+- Use responsibly and ethically
+- Respect local laws and regulations
+- Do not use for illegal activities
+- Understand the implications of anonymous communication
+
+---
+
+## 📜 License
+
+MIT License - See LICENSE file for details
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+**Security Issues:** Please report security vulnerabilities privately to the project maintainer
+
+---
+
+## 📞 Support
+
+- **Issues:** https://github.com/gabrix73/yamnweb/issues
+- **Repository:** https://github.com/gabrix73/yamnweb
+- **Community:** https://groups.google.com/g/alt.privacy.anon-server
 
 ---
 
-## 📚 Riferimenti
+## 🎖️ Credits
 
-- YAMN Documentation: https://mixmin.net/yamn.html
-- Tor Project: https://www.torproject.org/
-- Victor Yamn Pinger: https://echolot.virebent.art/
-- YAMN GitHub: https://github.com/crooks/yamn
+- **YAMN:** Created by [Zax/crooks](https://github.com/crooks)
+- **Tor Project:** https://www.torproject.org
+- **Mixmaster:** Original anonymous remailer protocol
+- **Remailer Community:** For maintaining the anonymous remailer network
 
 ---
 
-## 🔒 Note di Sicurezza
-
-**IMPORTANTE:**
-1. Disabilitare SEMPRE i log di Nginx
-2. Non salvare MAI metadata sensibili
-3. Tor SEMPRE obbligatorio per tutti i download e invii
-4. Verificare periodicamente che non ci siano file .log in /var/www/
-5. Mantenere aggiornati Tor e YAMN
-6. Usare HTTPS con TLS 1.3
-7. Rate limiting sempre attivo
-
-**Privacy:**
-- Nessun log IP
-- Nessun timestamp persistente
-- Replay protection attivo
-- Adaptive padding attivo
-- Randomized delays attivi
+**Status:** ✅ Operational | **Last Updated:** October 2025 | **Version:** 2.0
 
-- 
cgit v1.2.3