Roles and Permissions
======================

Role-Based Access Control (RBAC) implementation with hierarchical permissions.

.. contents:: Table of Contents
   :local:
   :depth: 2

Default Roles
-------------

.. list-table::
   :header-rows: 1
   :widths: 15 50 35

   * - Role
     - Permissions
     - Typical Users
   * - **admin**
     - All permissions, user management
     - System administrators
   * - **observer**
     - Create/update observations, register data
     - Observatory operators
   * - **viewer**
     - Read-only access
     - Scientists, collaborators
   * - **service**
     - Automated operations
     - Background services

Permission Model
----------------

Permissions follow pattern: ``action:resource``

Examples:

* ``read:observations``
* ``write:observations``
* ``delete:observations``
* ``manage:users``
* ``configure:system``

Decorators
----------

**Require roles**:

.. code-block:: python

   from ccat_ops_db_api.auth import require_roles
   
   @router.post("/admin/users")
   @require_roles("admin")
   async def create_user(
       user_data: UserCreate,
       current_user: User = Depends(get_current_user)
   ):
       # Only admins can create users
       ...

**Require permissions**:

.. code-block:: python

   from ccat_ops_db_api.auth import require_permissions
   
   @router.post("/executed_obs_units/start")
   @require_permissions("write:observations")
   async def start_observation(
       obs_data: ExecutedObsUnitCreate,
       current_user: User = Depends(get_current_user)
   ):
       # Users with write:observations permission
       ...

Helper Functions
----------------

.. code-block:: python

   from ccat_ops_db_api.auth import has_role, has_permission
   
   if has_role(current_user, "admin"):
       # Show admin options
       pass
   
   if has_permission(current_user, "delete:observations"):
       # Allow deletion
       pass

Database Schema
---------------

.. code-block:: sql

   CREATE TABLE user_role (
       user_id INTEGER REFERENCES "user"(id),
       role_id INTEGER REFERENCES role(id),
       PRIMARY KEY (user_id, role_id)
   );
   
   CREATE TABLE role_permission (
       role_id INTEGER REFERENCES role(id),
       permission_id INTEGER REFERENCES permission(id),
       PRIMARY KEY (role_id, permission_id)
   );

Next Steps
----------

* :doc:`../../tutorials/simple-endpoints/adding-authentication` - Tutorial