WellNuo/docs/ROLE_BASED_PERMISSIONS.md

Role-Based Permissions System

This document describes the role-based permissions system for beneficiary management in WellNuo.

User Roles

There are three user roles with different permission levels:

1. Custodian (Owner)

• Full access to all beneficiary features
• Can view and edit full beneficiary profile (name, address, avatar)
• Can manage access (invite/remove guardians and caretakers)
• Can manage subscription
• Can manage sensors/equipment
• Can remove beneficiary from their account

2. Guardian

• Most features available
• Can view beneficiary dashboard
• Can edit nickname only (personal display name)
• Can manage access (invite/remove other guardians and caretakers)
• Can view and manage subscription
• Can manage sensors/equipment
• Cannot remove beneficiary (only custodian can)

3. Caretaker

• Limited access for care providers
• Can view beneficiary dashboard
• Can edit nickname only (personal display name)
• Can view sensors/equipment
• Cannot manage access (cannot invite others)
• Cannot manage subscription
• Cannot remove beneficiary

Implementation

Menu Permissions (BeneficiaryMenu Component)

Location: components/ui/BeneficiaryMenu.tsx

The menu system automatically filters available actions based on user role:

const ROLE_PERMISSIONS: Record<UserRole, MenuItemId[]> = {
  custodian: ['dashboard', 'edit', 'access', 'subscription', 'sensors', 'remove'],
  guardian: ['dashboard', 'edit', 'access', 'subscription', 'sensors'],
  caretaker: ['dashboard', 'edit', 'sensors'],
};

Key features:

• Security-first: Defaults to caretaker (minimum permissions) if role not specified
• Menu items are filtered client-side based on userRole prop
• Backend validates permissions on API calls (double security)

Edit Modal (Beneficiary Detail Screen)

Location: app/(tabs)/beneficiaries/[id]/index.tsx

The edit functionality adapts based on user role:

Custodian Edit Form

if (isCustodian) {
  // Show full profile editor
  // Fields: avatar, name, address
  // Calls: api.updateWellNuoBeneficiary()
}

Custodian can edit:

• Avatar (photo upload)
• Full name
• Address

Guardian/Caretaker Edit Form

else {
  // Show nickname editor only
  // Fields: customName
  // Calls: api.updateBeneficiaryCustomName()
}

Guardian/Caretaker can edit:

• Custom nickname only (e.g., "Mom", "Dad", "Grandpa")
• Original name shown as reference (read-only)
• Nickname is personal to the user (not shared with others)

API Endpoints

For Custodians

• PATCH /api/me/beneficiaries/:id - Update name, address
• POST /api/me/beneficiaries/:id/avatar - Upload avatar
• DELETE /api/me/beneficiaries/:id - Remove access

For Guardians/Caretakers

• PATCH /api/me/beneficiaries/:id/custom-name - Update personal nickname

User Experience

Custodian Flow

1. Opens beneficiary detail screen
2. Clicks menu (three dots)
3. Sees all options including "Remove"
4. Clicks "Edit"
5. Modal shows: Avatar picker, Name field, Address field
6. Can update any field
7. Saves → Updates beneficiary table

Guardian Flow

1. Opens beneficiary detail screen
2. Clicks menu (three dots)
3. Sees all options except "Remove"
4. Clicks "Edit"
5. Modal shows: Nickname field only
6. Original name shown for reference
7. Saves → Updates user_access.custom_name

Caretaker Flow

1. Opens beneficiary detail screen
2. Clicks menu (three dots)
3. Sees only Dashboard, Edit, Sensors
4. Clicks "Edit"
5. Modal shows: Nickname field only
6. Original name shown for reference
7. Saves → Updates user_access.custom_name

Database Schema

-- beneficiaries table (custodian edits this)
beneficiaries {
  id: integer
  name: varchar (official name)
  address: varchar
  avatar: varchar (URL)
  ...
}

-- user_access table (guardians/caretakers edit custom_name)
user_access {
  id: integer
  user_id: integer (who has access)
  beneficiary_id: integer (which beneficiary)
  role: enum ('custodian', 'guardian', 'caretaker')
  custom_name: varchar (personal nickname)
  ...
}

Security Considerations

1. Client-side validation:

   • Menu items filtered by role
   • Edit modal shows different fields by role
   • Prevents accidental unauthorized actions

2. Server-side validation:

   • API endpoints check user's role before allowing action
   • Cannot bypass client checks with direct API calls
   • Returns 403 Forbidden if role insufficient

3. Default to minimum permissions:

   • If role is undefined, defaults to caretaker
   • "Fail secure" approach
   • Better to deny access than grant too much

Testing

Test files created:

• __tests__/components/BeneficiaryMenu.test.tsx - Menu permission tests
• __tests__/screens/BeneficiaryDetailScreen.test.tsx - Edit modal tests

Test coverage:

• ✅ Custodian sees all menu items
• ✅ Guardian sees all except Remove
• ✅ Caretaker sees limited menu items
• ✅ Custodian can edit full profile
• ✅ Guardian can edit nickname only
• ✅ Caretaker can edit nickname only
• ✅ Default role is caretaker (security)
• ✅ Navigation routes work correctly

Future Enhancements

Potential improvements:

1. Role-based access to specific sensors/devices
2. Granular permissions (e.g., "view subscription" vs "manage subscription")
3. Time-limited access (temporary caretaker access)
4. Audit log of permission changes
5. Role change notifications

Related Files

• components/ui/BeneficiaryMenu.tsx - Menu component with role filtering
• app/(tabs)/beneficiaries/[id]/index.tsx - Detail screen with role-based edit
• services/api.ts - API methods for role-based updates
• types/index.ts - TypeScript types for roles
• backend/src/routes/beneficiaries.js - Backend role validation

Questions?

For questions or issues related to role-based permissions:

1. Check this documentation
2. Review test files for examples
3. Check API endpoint documentation
4. Contact backend team for server-side validation logic