Security & RBAC

This section defines how an element becomes usable in the security workspace, how a developer makes a new feature secure by default, and how an agent creates task privileges and roles when a user asks for access.

The model

flowchart LR
    ELEMENT[Element<br/>model / menu / action / output] --> TASK[Privilege = one task]
    TASK --> ROLE[Role = job function]
    ROLE --> USER[User]

Element — a discovered target: a model, a display menu, an action, or an output/report. Elements are catalogued by rbac_sync and are never typed in free-hand.
Privilege — the lowest unit that can be granted. One privilege represents one task or screen, for example task.humanresource.employee.view or task.humanresource.employee.manage.
Role — the job function a user actually holds, for example HR_OFFICER. A role is made of one or more privileges.
User role — the assignment of a role to a user.

Do not grant a whole application by adding all of its elements to one privilege. Compose the job from tasks instead.

Default-deny rules

An element that is not in an active privilege assigned to an active role is denied.
Only is_superuser=True may reach an element that no privilege assigns. The fallback privilege function.unclassified.admin is not linked to any role.
Inactive roles, privileges, grants and targets contribute nothing.
Direct URLs are checked on the server. Hidden buttons are not a security boundary.
NORMAL_USER is a baseline role. Do not add admin or destructive tasks to it.

Naming conventions

Object	Format	Example
Functional bundle	`function.<key>.use` or `.admin`	`function.tasks.use`
Task privilege	`task.<app>.<object>.<operation>`	`task.humanresource.employee.manage`
Role	Uppercase code	`HR_OFFICER`
Model target	`model.<app_label>.<model_name>`	`model.humanresource.employee`
Menu target	`menu.<app_label>.<fasttab>.<url_name>`	`menu.humanresource.hremployees.humanresource_employee_list`
Module menu	`menu.<app_label>.__module__`	`menu.humanresource.__module__`
Action target	`action.<app_label>.<action_name>`	`action.humanresource.transfer_employee`
Output target	`output.<app_label>.<slug>.<variant>`	`output.humanresource.hr_employees.view`

function.* is reserved for seeded baseline bundles. New business access uses task.*.

Where to go next

Security readiness checklist — what a developer must do for every new element.
Creating roles and privileges — the agent playbook for access requests.
Troubleshooting access — unexpected access or 403s, Common dashboard access, the 403 template and rbac_sync failures.

The agent does not run tests or claim that access works. The user is solely responsible for testing and validation.