PSA/docs/security/permission-error-handling.md

Permission Error Handling

Overview

The application uses a consistent approach to handle permission-related errors with a distinct visual style to differentiate them from regular errors.

Error Handling Utility

The errorHandling.ts utility provides:

Client-side Functions

1. handleError(error, fallbackMessage?)

   • Automatically detects permission errors
   • Shows permission errors with:
     • ShieldAlert icon (from Lucide)
     • Light red background (#FEF2F2)
     • Dark red text (#991B1B)
     • Red border (#FCA5A5)
     • Longer duration (5 seconds)
   • Shows regular errors with default toast styling

2. isPermissionError(error)

   • Checks if an error message contains "Permission denied"
   • Returns boolean

3. useErrorHandler()

   • React hook that provides error handling utilities

Server-side Functions

1. throwPermissionError(action, additionalInfo?)
   • Throws consistent permission errors
   • Format: "Permission denied: You don't have permission to [action]. [additionalInfo]"

Usage Examples

In Components

import { handleError } from 'server/src/lib/utils/errorHandling';

try {
  await createTag({ ... });
} catch (error) {
  handleError(error, 'Failed to add tag');
}

In Server Actions

import { throwPermissionError } from 'server/src/lib/utils/errorHandling';

if (!await hasPermission(user, 'tag', 'create')) {
  throwPermissionError('create new tags', 'You can only select from existing tags');
}

Visual Examples

Permission Error

• Message: "Permission denied: You don't have permission to create new tags. You can only select from existing tags"
• Icon: ShieldAlert (Lucide icon in red)
• Background: Light red
• Duration: 5 seconds
• Style: Prominent border and coloring

Regular Error

• Message: "Failed to add tag"
• Icon: Default error icon
• Background: Default toast background
• Duration: Default (3 seconds)
• Style: Standard error toast

Benefits

1. Consistency: All permission errors look the same across the app
2. Clarity: Users immediately know when an action failed due to permissions
3. Helpfulness: Permission errors often include additional context
4. Maintainability: Single place to update permission error styling