telvero_whatson_talpa/plans/authentication-system-plan.md

# Authentication & Authorization System Plan

## Overzicht

Dit plan beschrijft de implementatie van een login systeem met rollen en rechten voor de Telvero Talpa Planning applicatie.

## Rollen & Rechten

### Admin Rol
- **Volledige toegang** tot alle functionaliteiten
- Kan infomercials toevoegen, bewerken en verwijderen
- Kan uitzendingen plannen, bewerken en verwijderen
- Kan synchroniseren met Talpa API
- Kan blokken beheren
- Kan gebruikers beheren (toevoegen, bewerken, verwijderen)

### Guest Rol
- **Alleen lezen** toegang
- Kan dashboards bekijken
- Kan planning bekijken (kalender, planner)
- Kan infomercials bekijken
- Kan blokken bekijken
- **Geen** toevoeg-, bewerk- of verwijderfunctionaliteit
- **Geen** sync functionaliteit
- **Geen** gebruikersbeheer

## Database Schema

### Tabel: `users`
```sql
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role ENUM('admin', 'guest') DEFAULT 'guest',
    is_active BOOLEAN DEFAULT 1,
    last_login TIMESTAMP NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_username (username),
    INDEX idx_email (email),
    INDEX idx_role (role)
);
```

### Tabel: `sessions`
```sql
CREATE TABLE sessions (
    id VARCHAR(128) PRIMARY KEY,
    user_id INT NOT NULL,
    ip_address VARCHAR(45),
    user_agent VARCHAR(255),
    last_activity TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    INDEX idx_user_id (user_id),
    INDEX idx_last_activity (last_activity)
);
```

### Tabel: `login_attempts`
```sql
CREATE TABLE login_attempts (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50),
    ip_address VARCHAR(45),
    success BOOLEAN DEFAULT 0,
    attempted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_username (username),
    INDEX idx_ip_address (ip_address),
    INDEX idx_attempted_at (attempted_at)
);
```

## Bestandsstructuur

```
/
├── auth/
│   ├── login.php              # Login pagina
│   ├── logout.php             # Logout handler
│   ├── auth_functions.php     # Authenticatie functies
│   └── middleware.php         # Access control middleware
├── admin/
│   └── users.php              # Gebruikersbeheer (admin only)
├── migrations/
│   └── 003_add_authentication.sql
└── (bestaande bestanden worden aangepast)
```

## Implementatie Details

### 1. Authenticatie Functies (`auth/auth_functions.php`)

```php
// Kernfuncties:
- login($username, $password)           // Inloggen
- logout()                              // Uitloggen
- isLoggedIn()                          // Check of gebruiker ingelogd is
- getCurrentUser()                      // Haal huidige gebruiker op
- hasRole($role)                        // Check of gebruiker rol heeft
- requireLogin()                        // Forceer login (redirect)
- requireRole($role)                    // Forceer specifieke rol
- hashPassword($password)               // Wachtwoord hashen
- verifyPassword($password, $hash)      // Wachtwoord verifiëren
- createSession($userId)                // Sessie aanmaken
- destroySession()                      // Sessie vernietigen
- logLoginAttempt($username, $success)  // Log inlogpoging
- checkBruteForce($username, $ip)       // Brute force bescherming
```

### 2. Middleware (`auth/middleware.php`)

```php
// Access control functies:
- checkAuthentication()                 // Check authenticatie
- checkAuthorization($requiredRole)     // Check autorisatie
- canCreate()                           // Kan aanmaken?
- canEdit()                             // Kan bewerken?
- canDelete()                           // Kan verwijderen?
- canSync()                             // Kan synchroniseren?
```

### 3. Login Pagina (`auth/login.php`)

**Features:**
- Username/email + wachtwoord formulier
- "Onthoud mij" functionaliteit
- Foutmeldingen bij ongeldige credentials
- Brute force bescherming (max 5 pogingen per 15 minuten)
- Redirect naar oorspronkelijke pagina na login
- Responsive design (Bootstrap)

### 4. Gebruikersbeheer (`admin/users.php`)

**Features (alleen voor admins):**
- Lijst van alle gebruikers
- Gebruiker toevoegen
- Gebruiker bewerken (username, email, rol)
- Gebruiker deactiveren/activeren
- Wachtwoord resetten
- Laatste login datum tonen
- Zoek- en filterfunctionaliteit

### 5. Bestaande Pagina's Aanpassen

Alle bestaande pagina's moeten worden aangepast:

#### Bovenaan elke pagina toevoegen:
```php
<?php
require_once __DIR__ . '/auth/auth_functions.php';
require_once __DIR__ . '/auth/middleware.php';

// Forceer login
requireLogin();

// Voor admin-only pagina's:
// requireRole('admin');
?>
```

#### Navigatie aanpassen:
- Gebruikersnaam tonen
- Logout knop toevoegen
- Rol badge tonen (Admin/Guest)

#### UI Aanpassingen voor Guest rol:

**Dashboard (`index.php`):**
- Verberg "Infomercial Registreren" formulier
- Verberg "Tijdblok Reserveren" formulier
- Verberg "Sync" knoppen
- Verberg "Opslaan" knoppen in Media Asset Management

**Planner (`planner.php`):**
- Verberg "Toevoegen" formulieren
- Verberg "Verwijderen" knoppen
- Verberg "Reorder" knoppen (pijltjes)
- Verberg "Sync" knoppen
- Verberg "Blok tijd aanpassen" knoppen
- Verberg "Kopieer blok" knoppen
- Disable drag-and-drop functionaliteit

**Kalender (`calendar.php`):**
- Disable drag-and-drop functionaliteit
- Verberg "Sync" knoppen
- Verberg "Verwijderen" knoppen in event modal
- Maak kalender read-only (geen event creation/editing)

**Blokken (`blocks.php`):**
- Verberg "Nieuw Template" knop
- Verberg "Bewerken" knoppen
- Verberg "Verwijderen" knoppen
- Verberg formulieren

**Infomercials (`infomercials.php`):**
- Verberg "Registreren" formulier
- Verberg "Bewerken" knoppen
- Verberg "Verwijderen" knoppen
- Verberg "Kleur aanpassen" functionaliteit

### 6. API Endpoints Beveiligen

Alle API endpoints in `/api/` moeten worden beveiligd:

```php
<?php
require_once __DIR__ . '/../auth/auth_functions.php';
require_once __DIR__ . '/../auth/middleware.php';

// Check authenticatie
if (!isLoggedIn()) {
    http_response_code(401);
    echo json_encode(['success' => false, 'error' => 'Niet geautoriseerd']);
    exit;
}

// Voor write operations (POST/PUT/DELETE):
if (!hasRole('admin')) {
    http_response_code(403);
    echo json_encode(['success' => false, 'error' => 'Geen toegang']);
    exit;
}
?>
```

**API endpoints die bescherming nodig hebben:**
- `create_transmission.php` - Admin only
- `update_transmission.php` - Admin only
- `delete_transmission.php` - Admin only
- `sync_block.php` - Admin only
- `copy_block.php` - Admin only
- `update_block_time.php` - Admin only
- `assign_color.php` - Admin only
- Read-only endpoints (`get_*.php`) - Alle ingelogde gebruikers

## Beveiliging

### Wachtwoord Beveiliging
- Gebruik `password_hash()` met `PASSWORD_BCRYPT` of `PASSWORD_ARGON2ID`
- Minimum wachtwoordlengte: 8 karakters
- Wachtwoord sterkte validatie (optioneel: hoofdletters, cijfers, speciale tekens)

### Sessie Beveiliging
- Gebruik PHP native sessions met secure settings
- Session timeout: 2 uur inactiviteit
- Regenerate session ID na login
- HttpOnly en Secure flags voor cookies (in productie)
- Session fixation bescherming

### Brute Force Bescherming
- Maximum 5 mislukte inlogpogingen per 15 minuten per username
- Maximum 10 mislukte inlogpogingen per 15 minuten per IP
- Lockout periode: 15 minuten
- Log alle inlogpogingen

### CSRF Bescherming
- CSRF tokens voor alle formulieren
- Token validatie bij POST requests
- Token regeneratie na gebruik

### SQL Injection Bescherming
- Gebruik prepared statements (reeds geïmplementeerd)
- Input validatie en sanitization

### XSS Bescherming
- Output escaping met `htmlspecialchars()` (reeds geïmplementeerd)
- Content Security Policy headers (optioneel)

## Environment Variabelen

Toevoegen aan `.env`:

```env
# Authentication Settings
AUTH_SESSION_TIMEOUT=7200
AUTH_MAX_LOGIN_ATTEMPTS=5
AUTH_LOCKOUT_DURATION=900
AUTH_REMEMBER_ME_DURATION=2592000
```

## Standaard Gebruikers

Bij installatie worden de volgende gebruikers aangemaakt:

```sql
-- Admin gebruiker
INSERT INTO users (username, email, password_hash, role) VALUES
('admin', 'admin@telvero.nl', '$2y$10$...', 'admin');

-- Guest gebruiker (voor demo)
INSERT INTO users (username, email, password_hash, role) VALUES
('guest', 'guest@telvero.nl', '$2y$10$...', 'guest');
```

**Standaard wachtwoorden:**
- Admin: `admin123` (moet bij eerste login worden gewijzigd)
- Guest: `guest123`

## UI/UX Overwegingen

### Login Pagina Design
- Centraal gepositioneerd formulier
- Telvero branding (logo, kleuren)
- Duidelijke foutmeldingen
- Loading indicator tijdens login
- Responsive design voor mobiel

### Navigatie Updates
```html
<div class="navbar-nav ms-auto">
    <span class="nav-link">
        <i class="bi bi-person-circle"></i> 
        <?= htmlspecialchars($_SESSION['user']['username']) ?>
        <span class="badge bg-<?= $_SESSION['user']['role'] === 'admin' ? 'danger' : 'secondary' ?>">
            <?= ucfirst($_SESSION['user']['role']) ?>
        </span>
    </span>
    <a class="nav-link" href="auth/logout.php">
        <i class="bi bi-box-arrow-right"></i> Uitloggen
    </a>
</div>
```

### Guest Mode Indicators
- Toon duidelijk dat gebruiker in "alleen lezen" modus is
- Tooltip bij disabled knoppen: "Alleen admins kunnen deze actie uitvoeren"
- Optioneel: banner bovenaan pagina voor guest gebruikers

## Testing Checklist

### Authenticatie Tests
- [ ] Login met geldige credentials (admin)
- [ ] Login met geldige credentials (guest)
- [ ] Login met ongeldige credentials
- [ ] Logout functionaliteit
- [ ] Session timeout na inactiviteit
- [ ] Brute force bescherming
- [ ] "Onthoud mij" functionaliteit
- [ ] Redirect naar oorspronkelijke pagina na login

### Autorisatie Tests
- [ ] Admin kan alle pagina's bezoeken
- [ ] Guest kan alleen lezen
- [ ] Guest kan geen create/update/delete acties uitvoeren
- [ ] Guest kan niet synchroniseren met Talpa
- [ ] API endpoints zijn beveiligd
- [ ] Direct URL access wordt geblokkeerd voor ongeautoriseerde acties

### UI Tests
- [ ] Knoppen zijn verborgen/disabled voor guests
- [ ] Formulieren zijn verborgen voor guests
- [ ] Drag-and-drop is disabled voor guests
- [ ] Navigatie toont correcte gebruikersinformatie
- [ ] Rol badge wordt correct getoond

### Gebruikersbeheer Tests (Admin only)
- [ ] Admin kan gebruikers toevoegen
- [ ] Admin kan gebruikers bewerken
- [ ] Admin kan gebruikers deactiveren
- [ ] Admin kan wachtwoorden resetten
- [ ] Guest kan gebruikersbeheer niet benaderen

## Migratie Strategie

### Stap 1: Database Migratie
```bash
mysql -u username -p talpa_planning < migrations/003_add_authentication.sql
```

### Stap 2: Standaard Gebruikers Aanmaken
Via SQL of via setup script

### Stap 3: Bestaande Pagina's Updaten
Alle PHP bestanden updaten met authenticatie checks

### Stap 4: Testing
Uitgebreid testen van alle functionaliteiten

### Stap 5: Deployment
- Backup maken van database
- Code deployen
- Migratie uitvoeren
- Testen in productie

## Toekomstige Uitbreidingen

Mogelijke uitbreidingen voor de toekomst:

1. **Meer Rollen:**
   - Editor: Kan plannen maar niet synchroniseren
   - Viewer: Alleen lezen (zoals guest)
   - Manager: Kan alles behalve gebruikersbeheer

2. **Granulaire Rechten:**
   - Per module rechten toewijzen
   - Custom permission sets

3. **Two-Factor Authentication (2FA):**
   - TOTP via Google Authenticator
   - SMS verificatie

4. **Audit Log:**
   - Log alle acties van gebruikers
   - Wie heeft wat wanneer gedaan

5. **Wachtwoord Beleid:**
   - Wachtwoord expiratie
   - Wachtwoord geschiedenis
   - Complexiteitseisen

6. **Single Sign-On (SSO):**
   - LDAP/Active Directory integratie
   - OAuth2 providers (Google, Microsoft)

7. **API Keys:**
   - Voor externe integraties
   - Rate limiting

## Documentatie Updates

Na implementatie moeten de volgende documenten worden bijgewerkt:

1. **README.md:**
   - Sectie over authenticatie toevoegen
   - Standaard credentials documenteren
   - Gebruikersbeheer uitleggen

2. **INSTALLATION.md:**
   - Authenticatie migratie stappen
   - Eerste admin gebruiker aanmaken

3. **Nieuwe documentatie:**
   - `docs/AUTHENTICATION.md` - Uitgebreide authenticatie documentatie
   - `docs/USER_MANAGEMENT.md` - Gebruikersbeheer handleiding

## Mermaid Diagram: Authenticatie Flow

```mermaid
graph TD
    A[Gebruiker bezoekt pagina] --> B{Ingelogd?}
    B -->|Nee| C[Redirect naar login.php]
    C --> D[Gebruiker vult credentials in]
    D --> E{Credentials geldig?}
    E -->|Nee| F[Toon foutmelding]
    F --> G{Max pogingen bereikt?}
    G -->|Ja| H[Account tijdelijk geblokkeerd]
    G -->|Nee| D
    E -->|Ja| I[Maak sessie aan]
    I --> J[Redirect naar oorspronkelijke pagina]
    B -->|Ja| K{Juiste rol?}
    K -->|Nee| L[Toon 403 Forbidden]
    K -->|Ja| M{Admin of Guest?}
    M -->|Admin| N[Volledige toegang]
    M -->|Guest| O[Alleen lezen toegang]
    N --> P[Toon alle functionaliteit]
    O --> Q[Verberg write acties]
```

## Mermaid Diagram: Database Schema

```mermaid
erDiagram
    users ||--o{ sessions : has
    users ||--o{ login_attempts : has
    
    users {
        int id PK
        varchar username UK
        varchar email UK
        varchar password_hash
        enum role
        boolean is_active
        timestamp last_login
        timestamp created_at
        timestamp updated_at
    }
    
    sessions {
        varchar id PK
        int user_id FK
        varchar ip_address
        varchar user_agent
        timestamp last_activity
        timestamp created_at
    }
    
    login_attempts {
        int id PK
        varchar username
        varchar ip_address
        boolean success
        timestamp attempted_at
    }
```

## Prioriteit & Volgorde

### Fase 1: Basis Authenticatie (Hoge Prioriteit)
1. Database migratie
2. Authenticatie functies
3. Login pagina
4. Logout functionaliteit
5. Sessie management

### Fase 2: Autorisatie (Hoge Prioriteit)
1. Middleware implementatie
2. Rol checks in bestaande pagina's
3. API beveiliging

### Fase 3: UI Aanpassingen (Gemiddelde Prioriteit)
1. Navigatie updates
2. Guest mode UI restrictions
3. Tooltips en indicators

### Fase 4: Gebruikersbeheer (Gemiddelde Prioriteit)
1. Gebruikersbeheer interface
2. CRUD operaties voor gebruikers
3. Wachtwoord reset functionaliteit

### Fase 5: Extra Beveiliging (Lage Prioriteit)
1. Brute force bescherming
2. CSRF tokens
3. Audit logging

## Conclusie

Dit plan biedt een complete oplossing voor authenticatie en autorisatie in de Telvero Talpa Planning applicatie. De implementatie zorgt voor:

- **Veilige authenticatie** met moderne best practices
- **Duidelijke rolscheiding** tussen admin en guest
- **Gebruiksvriendelijke interface** met duidelijke feedback
- **Uitbreidbaarheid** voor toekomstige requirements
- **Minimale impact** op bestaande functionaliteit

De implementatie kan gefaseerd worden uitgevoerd, waarbij eerst de basis authenticatie wordt geïmplementeerd en daarna stapsgewijs de autorisatie en UI aanpassingen worden toegevoegd.