Auth module (auth)

The auth module in src/cluster_erp/modules/auth/ signs users in and decides what they may do. It manages users, roles, permission codes, attribute policies, approval chains and requests, notification rules, revoked tokens, and each user's own interface state. Administrators use its screens; every other module uses it through modules/auth/guards.py and the EventBus. The mechanisms are explained on the pages of the identity and access section; this page is the module overview.

At a glance¶

What the module does¶

• Signs users in and out and issues, rotates, and revokes tokens; see authentication and sessions.
• Keeps the permission catalogue, roles, and user-role assignments and guards every route; see roles and permissions.
• Stores attribute policies that refine a permission; see ABAC policies.
• Runs approval chains for other modules; see approvals and approval chains.
• Stores notification rules; see notification rules.
• Stores each user's layout and preferences on the server (src/cluster_erp/modules/auth/ui_state/models.py:13-35); see user UI state.

Sub-modules¶

All routers are included under one module router (src/cluster_erp/modules/auth/module.py:32-70).

Data model¶

Every entity derives from BaseModel, so rows are soft-deleted; see soft delete and deactivation.

Screens and metadata¶

get_metadata declares one sidebar group, Authorization in English and Yetkilendirme in Turkish, with three sections: Users (list of user), Roles (list of role), and Settings with the tabs abac_policy, approval_chain, and notification_rule (src/cluster_erp/modules/auth/module.py:236-280). The labels come from metadata, not from the language files. The approver inbox My Approvals (webapp/i18n/en.json key approvals.inbox_title) is a home widget of the web app; see home widgets.

Status and actions¶

The auth metadata declares no ActionMeta; a grep for ActionMeta( in modules/auth finds none. Approval requests change status through their own routes; see approvals and approval chains.

Business rules¶

• A system role cannot be deleted (src/cluster_erp/modules/auth/roles/routes.py:104-105, src/cluster_erp/modules/auth/roles/services.py:72-80).
• Role and permission grants obey the privilege ceiling (src/cluster_erp/modules/auth/users/services.py:205-221, src/cluster_erp/modules/auth/roles/services.py:139-163).
• Creating a user with a taken user name answers a conflict (src/cluster_erp/modules/auth/users/routes.py:104-106).
• The first administrator is created only on an empty database (src/cluster_erp/modules/auth/users/services.py:412-453).
• A changed password ends all earlier sessions (src/cluster_erp/modules/auth/users/services.py:273-276).

Events and queries¶

Permissions¶

user.reset_password is not a CRUD code; it is in the extra seed list (src/cluster_erp/server/app.py:675). The admin role receives every seeded code (src/cluster_erp/modules/auth/roles/services.py:213-276).

Privacy, retention, and history¶

privacy_handlers.py returns the sign-in account (user name, e-mail, names, active flag, role codes, sign-in and sign-out times, creation time) and, on erasure, overwrites identifying columns, deactivates the account, and stamps last_logout_at (src/cluster_erp/modules/auth/privacy_handlers.py:1-104). The password hash is never exported and is redacted in change history (src/cluster_erp/modules/auth/privacy_handlers.py:7-8). Expired blacklist rows are deleted by the daily log retention (src/cluster_erp/server/app.py:1168-1192). auth_token_blacklist is excluded from change history; see change history.

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

Settings used by the module: secret_key, jwt_access_expire_minutes, jwt_refresh_expire_days, jwt_session_hours, jwt_refresh_reuse_grace_seconds, login_rate_limit_per_minute, auth_cache_seconds, abac_strict_permission_codes, and the bootstrap_admin_* settings (src/cluster_erp/config/settings.py:186-205, src/cluster_erp/config/settings.py:307-339). See the settings reference. Permission codes are seeded at every start-up (src/cluster_erp/server/app.py:634-948). The setting password_min_length is defined (src/cluster_erp/config/settings.py:327), but no code reads it at this commit (git grep password_min_length).

Tests¶

Found by file name and by a search for modules.auth imports in tests/, and by name in web-client/.

Terms introduced¶

Related pages¶

• Modules index
• API reference for this module
• Identity, access, tenancy, privacy, and licensing
• Roles and permissions

Verified against commit 92f8051 on 2026-11-13.