Permissions
Heelr uses a Role-Based Access Control (RBAC) system that governs what actions users can perform and what data they can see. Permissions are enforced at multiple layers to ensure security.
Role Hierarchy
Heelr has three roles, listed from lowest to highest permission level:
1. Volunteer (Entry Level)
- View Level 1 dogs on the dashboard
- Log activities for animals they can handle
- View activity history
- Read-only access to most features
- Volunteers with Special Handling Certification can also view and handle Special Handling dogs
2. Staff (Shelter Staff)
- Everything a volunteer can do, plus:
- View and handle all dogs (Staff Only, Isolation, PPE)
- Add new animals to the system
- Edit animal details, handling notes, and medical notes
- Upload and remove photos
- Edit and delete activities
- Start, update, and end behavior support plans (dogs only)
- Log behavior sessions (dogs only)
- View the Intelligence Dashboard (if enabled)
- Submit in-app feedback
3. Admin (Full Control)
- Everything staff can do, plus:
- Manage users (create, edit, deactivate, invite)
- Import animals via CSV
- View audit logs
- View and manage feedback
- Access all administrative features
- Manage shelter settings (including enabling Intelligence Dashboard)
Permission Matrix
| Feature | Volunteer | Volunteer (SH Certified) | Staff | Admin |
|---|---|---|---|---|
| Dogs | ||||
| View Level 1 dogs | Yes | Yes | Yes | Yes |
| View Special Handling dogs | No | Yes | Yes | Yes |
| View Staff Only / Isolation / PPE dogs | No | No | Yes | Yes |
| Add new animals | No | No | Yes | Yes |
| Edit animal details | No | No | Yes | Yes |
| Upload/remove photos | No | No | Yes | Yes |
| Edit handling notes | No | No | Yes | Yes |
| Edit medical notes | No | No | Yes | Yes |
| Import animals (CSV) | No | No | No | Yes |
| Activities | ||||
| Log activities | Yes | Yes | Yes | Yes |
| View activity history | Yes | Yes | Yes | Yes |
| Edit activities | No | No | Yes | Yes |
| Delete activities | No | No | Yes | Yes |
| Behavior Support (dogs only) | ||||
| View behavior support status | No | No | Yes | Yes |
| Start/update/end behavior support | No | No | Yes | Yes |
| Log behavior sessions | No | No | Yes | Yes |
| Users | ||||
| View user list | No | No | No | Yes |
| Add users | No | No | No | Yes |
| Edit users | No | No | No | Yes |
| Invite users | No | No | No | Yes |
| Deactivate users | No | No | No | Yes |
| Administration | ||||
| View audit logs | No | No | No | Yes |
| Manage shelter settings | No | No | No | Yes |
| Intelligence Dashboard | No | No | Yes* | Yes* |
| Submit feedback | No | No | Yes | Yes |
| View/manage feedback | No | No | No | Yes |
*Intelligence Dashboard requires the enable_intelligence_dashboard shelter setting to be turned on by an admin.
Handling Level Access
Dog access is controlled by handling levels -- a special permission that combines the dog's assigned level with the user's role and certification:
| Dog Handling Level | Volunteer | Volunteer (SH Certified) | Staff | Admin |
|---|---|---|---|---|
| Level 1 | Can handle | Can handle | Can handle | Can handle |
| Special Handling | Cannot handle | Can handle | Can handle | Can handle |
| Staff Only | Cannot handle | Cannot handle | Can handle | Can handle |
| Isolation | Cannot handle | Cannot handle | Can handle | Can handle |
| PPE | Cannot handle | Cannot handle | Can handle | Can handle |
Users can only see and log activities for dogs they're permitted to handle.
Cats and Other species do not have handling levels. They are visible to all users.
Three-Layer Enforcement
Permissions are enforced at three independent layers, creating a defense-in-depth security model:
1. Database Layer
The most secure layer. Row Level Security (RLS) policies in the database automatically filter queries based on the user's identity and role. This layer cannot be bypassed -- even if someone manipulated the application code, the database would still enforce the rules.
Key protections:
- Users can only see data from their own shelter (multi-tenant isolation)
- Dog queries are automatically filtered by handling level
- Write operations are restricted by role
- User management tables are admin-only
2. API Layer
Server-side permission checks run before any data modification. Every action (adding a dog, logging an activity, managing users) validates that the current user has the required role. If the check fails, the operation is rejected with a clear error message.
3. UI Layer
The user interface hides features the user doesn't have permission to use. For example, volunteers don't see the "Add Dog" button, and non-admins don't see the "Users" navigation link. This is purely for user experience -- the real security comes from the database and API layers.
Defense in Depth
Because permissions are enforced at all three layers independently:
- Modifying client-side code won't help -- the database blocks unauthorized access
- Calling the API directly won't help -- server-side checks reject unauthorized requests
- Cross-shelter access is impossible -- every query is scoped to the user's shelter
- Token manipulation won't help -- authentication is validated by Supabase
Even if one layer were compromised, the others would still protect the data.
Permission Denials
When a permission check fails:
- The user sees a clear message explaining they don't have access
- The denial is logged for security monitoring
- No data is exposed or modified
- The user is redirected to an appropriate page
This logging helps identify confused users (who may need training), UI bugs (where a button should have been hidden), or potential security issues.