# Security Architecture

## Overview

This document provides a visual representation of the security architecture implemented in the Survey Custom Certificate Template module.

## Security Layers

```
┌─────────────────────────────────────────────────────────────────┐
│                         USER INTERFACE                           │
│  - Form validation                                               │
│  - Field visibility based on groups                              │
│  - Client-side input constraints                                 │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ACCESS CONTROL LAYER                          │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Record Rules (ir.rule)                                    │  │
│  │  - Survey managers: Full access                           │  │
│  │  - Survey users: Read-only, own records                   │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Model Access (ir.model.access)                            │  │
│  │  - CRUD permissions per group                             │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Field-Level Security                                      │  │
│  │  - Sensitive fields restricted to managers                │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                   APPLICATION LAYER                              │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Input Validation                                          │  │
│  │  - _validate_placeholder_key()                            │  │
│  │  - _validate_json_structure()                             │  │
│  │  - _validate_and_sanitize_placeholders()                  │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Input Sanitization                                        │  │
│  │  - _sanitize_placeholder_value()                          │  │
│  │  - _sanitize_certificate_value()                          │  │
│  │  - HTML escaping, tag stripping                           │  │
│  │  - Control character removal                              │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Business Logic Validation                                 │  │
│  │  - File format validation                                 │  │
│  │  - File size limits                                       │  │
│  │  - Template structure validation                          │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    DATABASE LAYER                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Database Constraints (@api.constrains)                    │  │
│  │  - _check_source_key()                                    │  │
│  │  - _check_value_field()                                   │  │
│  │  - _check_custom_text()                                   │  │
│  │  - _check_custom_cert_mappings()                          │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Data Integrity                                            │  │
│  │  - Foreign key constraints                                │  │
│  │  - Required field enforcement                             │  │
│  │  - Data type validation                                   │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

## Data Flow with Security Checks

```
User Input
    │
    ▼
┌─────────────────────┐
│ UI Validation       │ ← Field constraints, required fields
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Access Control      │ ← Check user permissions
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Input Validation    │ ← Validate format, length, pattern
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Input Sanitization  │ ← Escape HTML, remove control chars
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Business Logic      │ ← Apply business rules
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│ Database Constraint │ ← Final validation at DB level
└──────┬──────────────┘
       │
       ▼
   Database
```

## Attack Surface and Mitigations

```
┌──────────────────────────────────────────────────────────────────┐
│                        ATTACK VECTORS                             │
└──────────────────────────────────────────────────────────────────┘

1. XSS (Cross-Site Scripting)
   Input: <script>alert('XSS')</script>
   ↓
   Mitigation: HTML escaping + tag stripping
   ↓
   Output: &lt;script&gt;alert('XSS')&lt;/script&gt; → (stripped)

2. SQL Injection
   Input: field'; DROP TABLE users--
   ↓
   Mitigation: Character whitelisting (alphanumeric, _, .)
   ↓
   Result: REJECTED (invalid characters)

3. Command Injection
   Input: field; rm -rf /
   ↓
   Mitigation: Pattern validation + character whitelisting
   ↓
   Result: REJECTED (invalid format)

4. Path Traversal
   Input: ../../etc/passwd
   ↓
   Mitigation: No path separators allowed in field names
   ↓
   Result: REJECTED (invalid characters)

5. DoS (Denial of Service)
   Input: 100MB file or 1,000,000 character text
   ↓
   Mitigation: File size limit (10MB) + text length limit (1000 chars)
   ↓
   Result: REJECTED (exceeds limits)

6. Data Corruption
   Input: Malformed JSON structure
   ↓
   Mitigation: JSON validation + structure validation
   ↓
   Result: REJECTED (invalid structure)
```

## Access Control Matrix

```
┌────────────────────────────────────────────────────────────────┐
│                    PERMISSION MATRIX                            │
├────────────────┬───────────┬───────────┬──────────┬────────────┤
│ Resource       │ Manager   │ User      │ Portal   │ Public     │
├────────────────┼───────────┼───────────┼──────────┼────────────┤
│ Wizard         │ CRUD      │ R (own)   │ None     │ None       │
│ Placeholder    │ CRUD      │ R (own)   │ None     │ None       │
│ Survey (cert)  │ CRUD      │ R (own)   │ None     │ None       │
│ Template File  │ RW        │ None      │ None     │ None       │
│ Mappings       │ RW        │ None      │ None     │ None       │
│ Has Cert Flag  │ RW        │ R         │ None     │ None       │
└────────────────┴───────────┴───────────┴──────────┴────────────┘

Legend:
  C = Create, R = Read, U = Update, D = Delete, W = Write
  (own) = Only records created by the user
```

## Validation Pipeline

```
┌─────────────────────────────────────────────────────────────────┐
│                    VALIDATION PIPELINE                           │
└─────────────────────────────────────────────────────────────────┘

Placeholder Key: {key.field_name}
    │
    ├─► Length Check (max 200 chars) ──────────► PASS/FAIL
    │
    ├─► Pattern Match (regex) ─────────────────► PASS/FAIL
    │       Pattern: ^\{key\.[a-zA-Z0-9_]+\}$
    │
    └─► Character Whitelist ───────────────────► PASS/FAIL
            Allowed: letters, numbers, _, {, }, .

Value Field: partner_id.name
    │
    ├─► Length Check (max 200 chars) ──────────► PASS/FAIL
    │
    ├─► Character Whitelist ───────────────────► PASS/FAIL
    │       Allowed: letters, numbers, _, .
    │
    └─► No Special Chars ──────────────────────► PASS/FAIL
            Rejected: -, ', ", ;, <, >, etc.

Custom Text: "Sample text"
    │
    ├─► Length Check (max 1000 chars) ─────────► PASS/FAIL
    │
    ├─► HTML Escape ───────────────────────────► SANITIZED
    │       < → &lt;, > → &gt;, etc.
    │
    ├─► Control Char Removal ──────────────────► SANITIZED
    │       Remove: \x00-\x08, \x0B-\x0C, etc.
    │
    └─► Tag Stripping ─────────────────────────► SANITIZED
            Remove: <script>, <img>, etc.

JSON Mappings: {"placeholders": [...]}
    │
    ├─► JSON Syntax Check ─────────────────────► PASS/FAIL
    │
    ├─► Structure Validation ──────────────────► PASS/FAIL
    │       Must be: dict with 'placeholders' list
    │
    ├─► Each Placeholder ──────────────────────► PASS/FAIL
    │       Required: 'key', 'value_type'
    │       Valid types: survey_field, user_field, custom_text
    │
    └─► Field Validation ──────────────────────► PASS/FAIL
            All fields validated individually
```

## Security Monitoring Points

```
┌─────────────────────────────────────────────────────────────────┐
│                    LOGGING & MONITORING                          │
└─────────────────────────────────────────────────────────────────┘

1. Authentication Events
   ├─► User login to wizard
   ├─► Permission denied attempts
   └─► Unauthorized access attempts

2. Validation Failures
   ├─► Invalid placeholder keys
   ├─► Malformed JSON
   ├─► Suspicious input patterns
   └─► File validation failures

3. Sanitization Events
   ├─► HTML tags removed
   ├─► Control characters stripped
   ├─► Long inputs truncated
   └─► Special characters rejected

4. Certificate Generation
   ├─► Generation attempts
   ├─► Generation failures
   ├─► LibreOffice errors
   └─► Data retrieval errors

5. Administrative Actions
   ├─► Template uploads
   ├─► Template deletions
   ├─► Mapping changes
   └─► Configuration updates
```

## Security Checklist

```
Pre-Deployment Security Checklist:

□ Access Control
  ├─□ Record rules configured
  ├─□ Model access defined
  ├─□ Field-level security set
  └─□ User groups assigned

□ Input Validation
  ├─□ Placeholder key validation
  ├─□ Field name validation
  ├─□ Text length validation
  └─□ JSON structure validation

□ Sanitization
  ├─□ HTML escaping enabled
  ├─□ Control char removal
  ├─□ Tag stripping active
  └─□ Length limiting enforced

□ Database Constraints
  ├─□ Constraints defined
  ├─□ Constraints tested
  └─□ Error handling proper

□ Testing
  ├─□ Security tests pass
  ├─□ Injection tests pass
  ├─□ XSS tests pass
  └─□ DoS tests pass

□ Documentation
  ├─□ Security guide complete
  ├─□ Quick reference available
  └─□ Admin guide updated

□ Monitoring
  ├─□ Logging configured
  ├─□ Alerts set up
  └─□ Audit trail enabled
```

## Threat Model

```
┌─────────────────────────────────────────────────────────────────┐
│                        THREAT MODEL                              │
└─────────────────────────────────────────────────────────────────┘

Threat: Malicious Template Upload
├─► Attack: Upload template with embedded malware
├─► Impact: Server compromise
├─► Likelihood: Medium
├─► Mitigation: File validation, DOCX structure check
└─► Residual Risk: Low

Threat: XSS via Custom Text
├─► Attack: Inject JavaScript in custom text fields
├─► Impact: User session hijacking
├─► Likelihood: High
├─► Mitigation: HTML escaping, tag stripping
└─► Residual Risk: Very Low

Threat: SQL Injection via Field Names
├─► Attack: Inject SQL in value_field
├─► Impact: Database compromise
├─► Likelihood: Medium
├─► Mitigation: Character whitelisting, ORM usage
└─► Residual Risk: Very Low

Threat: Unauthorized Access
├─► Attack: Access wizard without permissions
├─► Impact: Data exposure
├─► Likelihood: Medium
├─► Mitigation: Record rules, access control
└─► Residual Risk: Low

Threat: DoS via Large Files
├─► Attack: Upload very large template files
├─► Impact: Server resource exhaustion
├─► Likelihood: Low
├─► Mitigation: File size limits
└─► Residual Risk: Very Low

Threat: Data Corruption
├─► Attack: Save malformed JSON mappings
├─► Impact: Certificate generation failure
├─► Likelihood: Low
├─► Mitigation: JSON validation, constraints
└─► Residual Risk: Very Low
```

## Conclusion

The security architecture implements defense in depth with multiple layers of protection:

1. **Access Control**: Restricts who can perform actions
2. **Input Validation**: Ensures data is in expected format
3. **Sanitization**: Removes dangerous content
4. **Database Constraints**: Final validation layer
5. **Monitoring**: Detects and logs security events

This multi-layered approach ensures that even if one layer fails, others provide protection against common web application vulnerabilities.