Roles and permissions, checks on every endpoint, every change audited.
Spec — Role-based access control
Status: draft · Created: 2026-11-10
1. Context and goal
What each member may do depends on the roles they hold in the organization, so admins grant exactly what each person needs and can prove who changed what.
2. Functional requirements (EARS)
- FR-1: THE SYSTEM SHALL define each permission as an action on a resource type (for example
project:delete) and each role as a set of permissions. - FR-2: THE SYSTEM SHALL ship the built-in roles Owner, Admin, Member and Viewer, and answer 409 to any attempt to edit or delete them.
- FR-3: WHEN an admin creates or edits a custom role, THE SYSTEM SHALL accept only known permissions and answer 422 naming each unknown one.
- FR-4: THE SYSTEM SHALL check the caller's permission on every endpoint before running it, and answer 403 naming the missing permission when it is absent.
- FR-5: IF an endpoint declares no permission and is not marked public, THEN THE SYSTEM SHALL fail to start, so no route is open by default.
- FR-6: WHEN a member's roles change, THE SYSTEM SHALL apply the new permissions to their requests within 5 seconds.
- FR-7: IF a change would leave the organization without an Owner, or grant a permission the acting admin does not hold, THEN THE SYSTEM SHALL reject the first with 409 and the second with 403.
- FR-8: WHEN a role or a role assignment is created, changed or deleted, THE SYSTEM SHALL write an audit entry with the actor, the target, the values before and after, and the time.
- FR-9: WHEN an admin opens a member, THE SYSTEM SHALL list the member's effective permissions and the role that grants each one.
3. Out of scope
- Sharing of single records with individual people.
- Attribute-based policies.