Permissions Model

SpatiumDDI uses a group-based RBAC model. Users are members of one or more Groups, groups carry one or more Roles, and roles carry a list of Permission entries. Every API mutation is checked server-side (see non-negotiable #3 in CLAUDE.md).

The Permission Entry

Each entry in Role.permissions (JSONB) is an object with this shape:

{
  "action": "write",
  "resource_type": "subnet",
  "resource_id": "c3f1e7b9-2a5d-…"
}

Actions

Resource types

Evaluation rules

1. Superadmin short-circuits everything. If User.is_superadmin=True the check always passes (no audit denial written).
2. Inactive users are denied regardless of permissions.

“Effective superadmin” — legacy flag + RBAC wildcard

Two paths grant superadmin-level access (#190):

• Legacy column — User.is_superadmin=True set directly on the row (seeded admin, anyone explicitly flagged in the user-admin form).
• RBAC wildcard — the user is a member of a group whose role carries a {action: "*", resource_type: "*"} permission (the built-in Superadmin role or any clone of it).

Both pass require_permission gates identically. For endpoints with Depends(require_superadmin) (or an inline is_effective_superadmin check), both also admit — without this unification, users provisioned via LDAP / OIDC / SAML and mapped into a Superadmin-role group passed every require_permission check but 403’d on hand-rolled superadmin helpers (the canonical pre-#190 bug).

Carve-out: the legacy-flag path keeps admitting inactive superadmins so a disabled bootstrap admin can still reach diagnostic surfaces during incident triage. The wildcard-permission path still requires is_active=True because user_has_permission short-circuits on inactive.

1. Match algorithm for a given check (action, resource_type, resource_id):
   • Walk every role in every group the user is a member of.
   • A permission entry matches when:
     • entry.action == "*" or entry.action == action or (entry.action == "admin" and action ∈ {read, write, delete, admin}), AND
     • entry.resource_type == "*" or entry.resource_type == resource_type, AND
     • entry.resource_id is missing/empty/"*", OR entry.resource_id == resource_id.
   • Any single matching entry grants the permission.
2. Unscoped vs scoped checks. A permission with resource_id set cannot satisfy an unscoped check (one passed without resource_id). This prevents “I have write on this one subnet” from accidentally granting “write on subnets in general”.
3. Privilege ceiling on role / group edits (#400 C4). When a non-superadmin creates or edits a role’s permission set (or assigns roles to a group), every permission they add must be one they themselves effectively hold — user_has_permission(editor, entry) must pass for each entry in the new set. This stops, say, an IPAM editor from minting a {*, *} role and assigning it to their own group to escalate. Superadmins (either path in the section above) are exempt by rule 1.

Built-in roles (seeded on first start)

Built-in roles (is_builtin=True) can be cloned but not deleted.

Feature-module gating. The Change Approver role only matters when the default-off governance.approvals feature module is enabled, and Address Set Editor when ipam.address_sets is enabled.

Using the helpers

from app.core.permissions import require_resource_permission, user_has_permission

# Router-level: GET=read, POST/PUT=write, DELETE=delete
router = APIRouter(dependencies=[Depends(require_resource_permission("subnet"))])

# Fine-grained inside a handler:
subnet = await db.get(Subnet, subnet_id)
if not user_has_permission(current_user, "write", "subnet", subnet.id):
    raise HTTPException(403, "Permission denied on this subnet")

See backend/app/core/permissions.py for the full API.