igny8/docs/90-ARCHIVED/master-docs-original/00-system/05-PERMISSIONS-AND-ACCESS-CONTROL.md

Permissions and Access Control

Purpose

Explain role-based permissions, account ownership rules, and how viewsets enforce access across the stack.

Code Locations (exact paths)

• Role-based permissions: backend/igny8_core/auth/permissions.py
• User roles and helpers: backend/igny8_core/auth/models.py
• Account context middleware: backend/igny8_core/auth/middleware.py
• Base viewsets with override/bypass logic: backend/igny8_core/api/base.py
• DRF settings: backend/igny8_core/settings.py

High-Level Responsibilities

• Enforce role-based access (developer, owner, admin, editor, viewer, system_bot).
• Enforce tenant/site/sector scoping with selective overrides for privileged roles.
• Block access when accounts lack active plans.

Detailed Behavior

• Roles are stored on User.role; helper methods (is_admin_or_developer, is_developer, is_system_account_user, has_role) drive bypass logic.
• Permission classes:
  • IsOwnerOrAdmin: allows authenticated users with roles owner/admin/developer or superuser.
  • IsEditorOrAbove: allows editor/admin/owner/developer or superuser.
  • IsViewerOrAbove: allows any authenticated user.
  • AccountPermission: ensures the user is authenticated, not a system bot unless intended, and matches object account when present; system bots bypass account checks.
• Base viewsets:
  • AccountModelViewSet filters by account unless is_admin_or_developer or is_system_account_user is true; create sets account automatically; delete protects system account slugs.
  • SiteSectorModelViewSet extends filtering to site/sector when models have those fields.
• Middleware:
  • AccountContextMiddleware denies requests when user lacks an account or active plan (403/402), logging out session users and returning JSON errors.
• System accounts (aws-admin, default-account, default) and system bots are privileged; system accounts are protected from deletion.

Data Structures / Models Involved (no code)

• User with role and account FK.
• Account with status and plan used for gating.
• SiteUserAccess for per-site grants evaluated by User.get_accessible_sites.

Execution Flow

• Middleware validates account/plan and sets request.account.
• DRF authentication sets request.user; permission classes on views (and base viewsets) check role/account match.
• Querysets are filtered by tenant/site/sector; privileged roles may bypass filtering.
• Soft-delete or delete operations respect system account protection.

Cross-Module Interactions

• All module viewsets inherit base classes, so account/site/sector scoping and role-based bypass apply uniformly.
• Integration endpoints using API key auth rely on request.site/request.account set earlier.

State Transitions (if applicable)

• Account status and plan activation affect access; changing these alters middleware decisions immediately due to per-request user refresh.

Error Handling

• Middleware returns structured JSON errors for missing account or inactive plan.
• Base viewsets wrap permission and validation failures into unified error responses.
• Permission classes return standard DRF permission denials for unauthenticated/unauthorized users.

Tenancy Rules

• Default: filter data to request.account; site/sector models further constrain by site/sector.
• Overrides: developers/admins/system-account users can see across accounts; system bots can access any account/object; system accounts cannot be deleted.

Billing Rules (if applicable)

• Active plan required; enforced in middleware before permission checks.

Background Tasks / Schedulers (if applicable)

• Background tasks should be invoked with account/site identifiers to maintain the same isolation rules; role checks occur at request time, not within tasks.

Key Design Considerations

• Centralize role checks to avoid per-view duplication.
• Maintain middleware-first gating to prevent expensive processing before authorization.
• Preserve protection of system accounts and allow ops-level overrides without compromising tenant isolation.

How Developers Should Work With This Module

• Apply permission classes (IsOwnerOrAdmin, IsEditorOrAbove, etc.) on viewsets/endpoints as needed.
• Always inherit from AccountModelViewSet/SiteSectorModelViewSet for scoped data access.
• Avoid bypassing middleware plan checks; if admin-only, use explicit admin routes instead.
• When adding new privileged behaviors, reuse User role helpers and system-account detection.