Security Rules Documentation

Comprehensive guide to Toto's Firebase security rules for Firestore and Storage, ensuring data protection and proper access control.

📊 Overview

The Toto ecosystem implements enterprise-grade security rules that provide:

• Role-based access control (admin, guardian, user, investor, partner)
• Data isolation - users can only access their own data
• Admin oversight - administrators can manage all collections
• Guardian permissions - case managers can create and update cases
• Secure file storage - organized path-based permissions

🔥 Firestore Security Rules

Core Principles

Authentication Required

• All operations require user authentication (request.auth != null)
• Unauthenticated users are denied access to all data

Role-Based Permissions

function hasRole(role) {
  return isAuthenticated() && 
         get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == role;
}

Data Ownership

function isOwner(userId) {
  return isAuthenticated() && 
         request.auth.uid == userId;
}

Collection-Specific Rules

Users Collection (/users/{userId})

• Read: Users can read their own profile, admins can read all
• Update: Users can update own profile (except role), admins can update any
• Create: Only admins can create users
• Delete: Only admins can delete users

Cases Collection (/cases/{caseId})

• Read: All authenticated users can read cases
• Create: Guardians and admins can create cases
• Update: Case owners (guardians) and admins can update
• Delete: Only admins can delete cases

Donations Collection (/donations/{donationId})

• Read: Donors can read their own donations, admins can read all
• Create: Authenticated users can create donations for themselves
• Update/Delete: Only admins can modify donations

Notifications Collection (/notifications/{notificationId})

• Read: Users can read their own notifications, admins can read all
• Create: Only admins and system can create notifications
• Update: Users can mark own notifications as read, admins can update any
• Delete: Users can delete own notifications, admins can delete any

Support Tickets (/support_tickets/{ticketId})

• Read: Users can read their own tickets, admins can read all
• Create: Authenticated users can create tickets for themselves
• Update: Users can update limited fields, admins can update any
• Delete: Only admins can delete tickets

Audit Logs (/audit_logs/{logId})

• Read: Only admins can read audit logs
• Create: Only admins can create audit logs
• Update/Delete: Immutable - no updates allowed

Security Helpers

// Authentication check
function isAuthenticated() {
  return request.auth != null;
}

// Admin permission check  
function isAdmin() {
  return isAuthenticated() && 
         get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';
}

// Role-based permission check
function hasRole(role) {
  return isAuthenticated() && 
         get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == role;
}

// Data ownership check
function isOwner(userId) {
  return isAuthenticated() && 
         request.auth.uid == userId;
}

📁 Storage Security Rules

File Organization Structure

/profile_images/{userId}/     - User profile pictures
/case_images/{caseId}/        - Case photos and documentation  
/documents/{userId}/          - User document uploads
/optimized_images/            - System-processed images
/temp_uploads/{userId}/       - Temporary file uploads
/admin_uploads/               - Admin-only file storage

Access Control Patterns

User-Owned Files (/profile_images/{userId}/, /documents/{userId}/)

• Users can read/write their own files
• Admins can read/write any user's files

Public Read, Controlled Write (/case_images/{caseId}/)

• All authenticated users can read case images
• Only guardians and admins can upload case images
• Only admins can delete case images

System-Only Access (/optimized_images/)

• All authenticated users can read optimized images
• Only system/Cloud Functions can write (no direct user access)

Admin-Only Access (/admin_uploads/)

• Only administrators can read/write admin files

Storage Helper Functions

// Check if user is authenticated
function isAuthenticated() {
  return request.auth != null;
}

// Check if user is admin via Firestore lookup
function isAdmin() {
  return isAuthenticated() && 
         firestore.get(/databases/(default)/documents/users/$(request.auth.uid)).data.role == 'admin';
}

// Check if user is guardian via Firestore lookup  
function isGuardian() {
  return isAuthenticated() && 
         firestore.get(/databases/(default)/documents/users/$(request.auth.uid)).data.role == 'guardian';
}

// Check if user owns the file path
function isOwner(userId) {
  return isAuthenticated() && request.auth.uid == userId;
}

🚀 Deployment

Files Location

• Firestore Rules: firestore.rules
• Storage Rules: storage.rules
• Configuration: firebase.json

Configuration (firebase.json)

{
  "firestore": {
    "rules": "firestore.rules",
    "indexes": "firestore.indexes.json"
  },
  "storage": {
    "rules": "storage.rules"
  }
}

Deployment Commands

Deploy to Staging

firebase use toto-f9d2f-stg
firebase deploy --only firestore:rules,storage

Deploy to Production

firebase use toto-f9d2f  
firebase deploy --only firestore:rules,storage

🔍 Security Validation

Testing Security Rules

Valid Access Patterns

• ✅ User reads own profile
• ✅ Admin reads any user profile
• ✅ Guardian creates case
• ✅ User creates donation for themselves
• ✅ User marks own notification as read

Invalid Access Patterns

• ❌ User reads another user's profile
• ❌ User creates donation for another user
• ❌ Unauthenticated access to any data
• ❌ User attempts to read audit logs
• ❌ User attempts to modify their role

Security Monitoring

Audit Logging

• All administrative actions are logged to audit_logs
• Logs include user ID, action, timestamp, and details
• Only administrators can access audit logs

Access Patterns

• Monitor for unusual access patterns
• Alert on failed authentication attempts
• Track admin privilege usage

📋 Best Practices

Development

• Test security rules in Firebase emulator before deployment
• Use role-based permissions consistently
• Always validate user authentication before data access

Production

• Deploy security rules before seeding data
• Monitor audit logs for security incidents
• Regularly review and update security rules
• Implement principle of least privilege

Maintenance

• Document any rule changes with reasoning
• Test rule changes in staging before production
• Keep backup of working security rules
• Review rules during security audits

🚨 Emergency Procedures

Security Incident Response

1. Immediate: Disable affected user accounts via Firebase Console
2. Analysis: Review audit logs for scope of access
3. Containment: Update security rules to prevent further access
4. Recovery: Restore compromised data from backups
5. Prevention: Update rules and monitoring to prevent recurrence

Rule Rollback

# Keep previous working rules as backup
cp firestore.rules firestore.rules.backup
cp storage.rules storage.rules.backup

# Deploy previous version if needed
firebase deploy --only firestore:rules,storage

---

This security implementation ensures enterprise-grade protection for user data while enabling the necessary functionality for the Toto pet rescue platform.