Documentazione Tecnica

1. Architettura del Sistema
2. Struttura dei File
3. Schema del Database
4. Flusso di Autenticazione
5. Sistema dei Livelli
6. Formato appinfo.txt
7. Come Aggiungere una Nuova Applicazione
8. Misure di Sicurezza
9. API Interne (functions.php)
10. Manutenzione e Amministrazione

1.1 Panoramica

O-Hub è un portale web modulare progettato per ospitare e distribuire applicazioni web (utility, strumenti didattici, tool di produttività) con un sistema di controllo degli accessi basato su livelli.

1.2 Stack Tecnologico

• Backend: PHP 8.x (procedurale con funzioni organizzate)
• Database: MariaDB/MySQL con charset UTF-8 MB4
• Frontend: HTML5, CSS3 (custom, senza framework), JavaScript vanilla
• Sicurezza: bcrypt, CSRF tokens, prepared statements, rate limiting
• Server: Apache con mod_rewrite

1.3 Design Pattern

Il sistema adotta un approccio page-based (ogni file PHP è una pagina completa) con componenti condivisi tramite include. Questo modello è stato scelto per:

• Semplicità didattica: ogni file è autoesplicativo e può essere studiato isolatamente;
• Basso overhead: nessun framework, nessun autoloader complesso, caricamento diretto;
• Manutenibilità: le funzioni comuni sono centralizzate in functions.php.

1.4 Diagramma di Flusso

    Utente
      |
      v
  [Browser] --HTTPS--> [Apache + mod_rewrite]
      |                         |
      |                    [index.php]
      |                    [login.php]
      |                    [register.php]  --> [mail()]
      |                    [admin.php]
      |                    [profile.php]
      |                         |
      |                  [includes/]
      |                  ├── config.php      (costanti)
      |                  ├── functions.php   (logica)
      |                  ├── header.php      (template)
      |                  └── footer.php      (template)
      |                         |
      |                    [PDO] --> [MariaDB: o_hub]
      |                                ├── users
      |                                └── login_log
      |
      v
  [/apps/**/appinfo.txt] --> Scanner --> Card Grid
            

/var/www/html/o/
├── index.php              # Pagina principale (elenco app)
├── login.php              # Autenticazione utente
├── logout.php             # Disconnessione e distruzione sessione
├── register.php           # Registrazione nuovo utente
├── activate.php           # Verifica email (via token)
├── profile.php            # Profilo utente (modifica password, eliminazione)
├── admin.php              # Pannello di amministrazione
├── disclaimer.php         # Privacy policy + disclaimer GPL
├── .htaccess              # Configurazione Apache
│
├── includes/
│   ├── config.php         # Costanti di configurazione
│   ├── functions.php      # Funzioni di utilità (DB, auth, scanner, email)
│   ├── header.php         # Template header + navbar
│   └── footer.php         # Template footer + system monitor
│
├── assets/
│   └── style.css          # Foglio di stile principale
│
├── docs/
│   └── index.php          # Questa documentazione
│
└── apps/                  # Directory delle applicazioni
    └── pdf_manager/       # Esempio di applicazione
        ├── appinfo.txt    # Metadati dell'applicazione
        ├── index.html     # Interfaccia dell'applicazione
        └── api.php        # Backend dell'applicazione
            

3.1 Tabella users

Contiene tutti gli utenti registrati del sistema.

3.2 Tabella login_log

Registro cronologico di tutti i tentativi di accesso per sicurezza e auditing.

Il sistema implementa un flusso di registrazione a doppia verifica (email + admin), progettato per garantire che solo utenti verificati e autorizzati possano accedere alle risorse.

4.1 Registrazione

1. L'utente compila il modulo con: nome, cognome, email, tipo, password e (opzionalmente) sito web.
2. L'utente accetta l'informativa sulla privacy (checkbox obbligatorio).
3. Il sistema valida tutti i campi (lunghezza, formato email, unicità, forza password).
4. La password viene hashata con password_hash() usando bcrypt (cost 12).
5. Viene generato un token di attivazione casuale di 64 caratteri esadecimali (random_bytes(32)).
6. L'utente viene inserito nel DB con stato in_attesa, livello 1.
7. Viene inviata un'email con il link di attivazione.
8. L'amministratore riceve una notifica email.

4.2 Attivazione Email

1. L'utente clicca il link nell'email.
2. Il sistema verifica il token (esistenza, formato, scadenza di 24 ore).
3. Il campo email_verificata viene impostato a 1.
4. Il token viene invalidato (impostato a NULL).

4.3 Approvazione Admin

1. L'amministratore accede al pannello admin.
2. Nella sezione "Utenti" visualizza gli account in attesa.
3. Cliccando "Approva", il campo approvato_admin viene impostato a 1 e lo stato diventa attivo.
4. L'utente riceve un'email di conferma attivazione.

4.4 Login

1. L'utente inserisce email e password.
2. Il sistema verifica il rate limiting (max 5 tentativi falliti in 15 minuti).
3. La password viene verificata con password_verify() contro l'hash bcrypt.
4. Il sistema controlla: email verificata, approvazione admin, account non bloccato.
5. La sessione viene rigenerata (session_regenerate_id(true)) per prevenire session fixation.
6. L'ultimo accesso viene aggiornato e l'evento viene registrato in login_log.

Il sistema implementa una gerarchia di accesso a 10 livelli (0–9). Ogni applicazione dichiara nel file appinfo.txt il livello minimo richiesto per l'accesso.

Ogni applicazione deve contenere un file appinfo.txt nella propria directory root. Il file utilizza un formato chiave-valore semplice (una coppia per riga, separata da :).

6.1 Campi Supportati

6.2 Esempio Completo

nome: PDF Manager
versione: 1.0.0
descrizione: Strumento per unire, dividere e comprimere file PDF
livello: 1
pubblicato: si
icona: 📄

6.3 Note Importanti

• Il parser è case-insensitive per le chiavi (Nome, NOME, nome sono equivalenti).
• Sono supportate anche le varianti inglesi: name, version, description, level, published, icon.
• Le app senza appinfo.txt vengono mostrate nel pannello admin ma non nella pagina pubblica.
• Il campo pubblicato accetta: si, sì, yes, 1, true (case-insensitive).

Aggiungere una nuova applicazione al portale è un processo semplice in tre passi:

Passo 1: Crea la directory

mkdir /var/www/html/o/apps/mia_app

Passo 2: Crea il file appinfo.txt

nome: La Mia App
versione: 1.0.0
descrizione: Descrizione della mia applicazione
livello: 1
pubblicato: si
icona: ⚙

Passo 3: Inserisci i file dell'applicazione

Inserisci nella directory tutti i file dell'applicazione (index.html/index.php, CSS, JavaScript, ecc.). Il sistema punta automaticamente alla root della directory.

Il sistema implementa multiple difese a più livelli, seguendo il principio della defense in depth:

8.1 Autenticazione

• bcrypt (cost 12): algoritmo di hashing adattivo che rende impraticabili gli attacchi di forza bruta offline.
• Rate limiting: massimo 5 tentativi di login falliti per IP in 15 minuti.
• Session regeneration: l'ID di sessione viene rigenerato al login per prevenire session fixation.
• Doppia verifica: email + approvazione admin prima dell'attivazione.

8.2 Protezione da Attacchi

• CSRF: ogni form include un token CSRF univoco verificato server-side.
• SQL Injection: tutte le query usano prepared statements (PDO).
• XSS: tutti gli output sono sanitizzati con htmlspecialchars() (funzione e()).
• Cookie sicuri: flag HttpOnly, Secure e SameSite=Strict.
• Input validation: tutti gli input vengono validati e sanitizzati.

8.3 Accesso ai File

• La directory includes/ è protetta da accesso diretto via .htaccess.
• Il file config.php contiene le credenziali e non deve mai essere esposto.

Il file includes/functions.php espone le seguenti funzioni pubbliche:

Database

• db(): PDO — Ritorna un'istanza singleton della connessione PDO al database.

Sessione & Autenticazione

• init_session(): void — Inizializza la sessione con parametri di sicurezza.
• is_logged_in(): bool — Verifica se l'utente è autenticato.
• current_user(): ?array — Ritorna i dati dell'utente corrente (cached).
• require_login(): void — Redirect a login se non autenticato.
• require_admin(): void — Blocca con 403 se livello < 8.
• user_level(): int — Ritorna il livello numerico dell'utente (0 se non loggato).

Sicurezza

• csrf_token(): string — Genera/ritorna il token CSRF della sessione.
• csrf_field(): string — Ritorna l'input hidden HTML con il token CSRF.
• verify_csrf(): bool — Verifica il token CSRF dal POST.
• e(string): string — Alias per htmlspecialchars() con flag sicuri.
• clean_input(string): string — Trim e strip_tags dell'input.

Scanner Applicazioni

• scan_apps(int $level): array — Scansiona le app accessibili al livello dato.
• scan_all_apps(): array — Scansiona tutte le app (per il pannello admin).
• parse_appinfo(string $path): ?array — Parsa un singolo file appinfo.txt.

Sistema

• system_load(): array — Ritorna CPU load, memoria, disco e uptime.
• format_bytes(float, int): string — Formatta bytes in unità leggibili.

Email

• send_activation_email(email, nome, token): bool — Invia l'email di attivazione.
• send_admin_notification(nome, cognome, email, tipo): bool — Notifica l'admin.

Flash Messages

• flash(type, message): void — Accoda un messaggio flash.
• get_flashes(): array — Ritorna e svuota i messaggi flash.
• render_flashes(): string — Genera l'HTML dei messaggi flash.

10.1 Credenziali Admin Predefinite

• Email: admin@localhost
• Password: admin
• Livello: 9 (Super Amministratore)

10.2 Pulizia Log di Accesso

I log di accesso possono crescere nel tempo. Per ripulirli (mantenendo gli ultimi 90 giorni):

DELETE FROM login_log WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY);

10.3 Backup

Per un backup completo del sistema:

# Backup database
mysqldump o_hub > o_hub_backup_$(date +%Y%m%d).sql

# Backup file
tar -czf o_hub_files_$(date +%Y%m%d).tar.gz /var/www/html/o/

10.4 Aggiornamento

Per aggiornare il sistema, sostituire i file PHP mantenendo inalterati config.php e la directory apps/. Verificare sempre la compatibilità dello schema del database.