calminer/docs/architecture/08_concepts/08_01_security.md

User Roles and Permissions Model

This document outlines the proposed user roles and permissions model for the CalMiner application.

User Roles

• Admin: Full access to all features, including user management, application settings, and all data.
• Analyst: Can create, view, edit, and delete scenarios, run simulations, and view reports. Cannot modify application settings or manage users.
• Viewer: Can view scenarios, simulations, and reports. Cannot create, edit, or delete anything.

Permissions (examples)

• users:manage: Admin only.
• settings:manage: Admin only.
• scenarios:create: Admin, Analyst.
• scenarios:view: Admin, Analyst, Viewer.
• scenarios:edit: Admin, Analyst.
• scenarios:delete: Admin, Analyst.
• simulations:run: Admin, Analyst.
• simulations:view: Admin, Analyst, Viewer.
• reports:view: Admin, Analyst, Viewer.

Authentication System

The authentication system uses JWT (JSON Web Tokens) for securing API endpoints. Users can register with a username, email, and password. Passwords are hashed using a passlib CryptContext for secure, configurable hashing. Upon successful login, an access token is issued, which must be included in subsequent requests for protected resources.

Key Components

• Password Hashing: passlib.context.CryptContext with bcrypt scheme.
• Token Creation & Verification: jose.jwt for encoding and decoding JWTs.
• Authentication Flow:
  1. User registers via /users/register.
  2. User logs in via /users/login to obtain an access token.
  3. The access token is sent in the Authorization header (Bearer token) for protected routes.
  4. The get_current_user dependency verifies the token and retrieves the authenticated user.
• Password Reset: A placeholder forgot_password endpoint is available, and a reset_password endpoint allows users to set a new password with a valid token (token generation and email sending are not yet implemented).