calminer-docs/architecture/08_concepts/03_security.md

Security Concept

CalMiner places a strong emphasis on security to protect sensitive data and ensure the integrity of the system. The following security measures and practices are implemented to safeguard the platform:

Data Encryption

All sensitive data is encrypted at rest and in transit to prevent unauthorized access.

Access Controls

Role-based access controls (RBAC) are implemented to restrict data access based on user roles and responsibilities.

Also see Authentication and Authorization and the Data Model sections.

• Default administrative credentials are provided at deployment time through environment variables (CALMINER_SEED_ADMIN_EMAIL, CALMINER_SEED_ADMIN_USERNAME, CALMINER_SEED_ADMIN_PASSWORD, CALMINER_SEED_ADMIN_ROLES). These values are consumed by a shared bootstrap helper on application startup, ensuring mandatory roles and the administrator account exist before any user interaction.
• Operators can request a managed credential reset by setting CALMINER_SEED_FORCE=true. On the next startup the helper rotates the admin password and reapplies role assignments, so downstream environments must update stored secrets immediately after the reset.
• The bootstrap helper is idempotent; when no changes are required, startup completes without mutating the database, preserving audit trails while still verifying the presence of required roles.

Route Guard Dependencies

• require_project_resource and require_scenario_resource build on service-level authorization helpers to enforce role checks while resolving requested entities.
• require_project_scenario_resource ensures the scenario referenced by a request belongs to the provided project identifier before continuing processing.
• These dependencies surface 401/403/404 responses consistently across API and UI handlers and can be composed with additional ownership checks when project member metadata is introduced.

Session Management

Authentication relies on a pair of signing tokens issued as calminer_access_token and calminer_refresh_token HttpOnly cookies. An AuthSessionMiddleware component validates incoming access tokens, refreshes them when still covered by a valid refresh token, and attaches the resolved user context to request.state.auth_session. Logout clears both cookies and redirects users back to the login form. This approach keeps credentials out of JavaScript, supports transparent rotation of short-lived access tokens, and ensures templates can adapt their navigation to the current session state.

Audit Logging

Comprehensive logging of user activities and system events is maintained for monitoring and auditing purposes. Also see Error Handling and Logging section for more details.

Vulnerability Management

Regular security assessments and updates are conducted to identify and mitigate potential vulnerabilities.

Compliance

The system adheres to relevant regulatory requirements, such as GDPR, to ensure data privacy and protection.

Architectural Diagram with Security Layers

architecture-beta
    group SecurityLayers[Security Layers]

    service FrontendLayer(server)[Frontend Layer] in SecurityLayers
    service APILayer(server)[API Layer] in SecurityLayers
    service ServiceLayer(server)[Service Layer] in SecurityLayers
    service DataAccessLayer(server)[Data Access Layer] in SecurityLayers
    service DatabaseSystem(database)[Database System] in SecurityLayers
    service DataStorage(disk)[Encrypted Data Storage] in SecurityLayers

    FrontendLayer:R -- L:APILayer
    APILayer:R -- L:ServiceLayer
    ServiceLayer:R -- L:DataAccessLayer
    DataAccessLayer:R -- L:DatabaseSystem
    DatabaseSystem:B -- T:DataStorage

flowchart TD
    subgraph F[Frontend Layer]
        Frontend[Frontend Components]
    end
    subgraph A[API Layer]
        APILayer[API Layer]
    end
    subgraph S[Service Layer]
        ServiceLayer[Service Layer]
    end
    subgraph D[Data Access Layer]
        DataAccessLayer[Data Access Layer]
    end
    subgraph DB[Database System]

        DatabaseSystem[Database System]
        DataStorage[Encrypted Data Storage]
    end
    Frontend -->|Secure API Calls| APILayer
    APILayer -->|Authentication & Authorization| ServiceLayer
    ServiceLayer -->|Data Access| DataAccessLayer
    DataAccessLayer -->|Database Queries| DatabaseSystem
    DatabaseSystem -->|Encrypted Data Storage| DataStorage

    classDef securityLayer fill:#f96,stroke:#333,stroke-width:2px;
    class Frontend,APILayer,ServiceLayer,DataAccessLayer,DatabaseSystem securityLayer;

Level 2: Security Layers Explanation

Frontend Layer

The Frontend Layer implements secure communication protocols (e.g., HTTPS) to ensure data transmitted between the client and server is encrypted. It also incorporates input validation to prevent common vulnerabilities such as XSS and CSRF attacks.

API Layer

The API Layer enforces authentication and authorization mechanisms to control access to backend services. It validates incoming requests and ensures that only authorized users can access specific resources.

Service Layer

The Service Layer handles business logic while ensuring that data processing adheres to security policies. It also manages session security and implements rate limiting to prevent abuse.

Data Access Layer

The Data Access Layer is responsible for securely interacting with the database. It uses parameterized queries to prevent SQL injection attacks and ensures that data access is logged for auditing purposes.

Database System

The Database System employs encryption at rest and in transit to protect sensitive data. It also implements access controls to restrict database access based on user roles. Data is regularly backed up, and recovery procedures are in place to ensure data integrity in case of failures.

Encrypted Data Storage

All sensitive data stored in the system is encrypted using industry-standard encryption algorithms. This ensures that even if data storage is compromised, the data remains protected and inaccessible to unauthorized users.