[Enhancement]: Example Feature Using Template

[kstij]

What features would you like to see added?

Overview

Introduce role/permission-based authorization for the bulk delete brains endpoint (DELETE /web/brains/deleteall). Currently, the endpoint is only protected by authentication, meaning any logged-in user can trigger a destructive operation. Adding granular permissions ensures that only explicitly authorized roles (e.g., COMPANY, MANAGER) can perform this action.

This feature improves security, compliance, and consistency across the API surface.

Affected Area / Components

• API Endpoint: DELETE /web/brains/deleteall
• Route file: nodejs/src/routes/web/brains.js
• Controller: nodejs/src/controller/web/brainController.js
• Middleware: nodejs/src/middleware/authentication.js, nodejs/src/middleware/authorization.js (new/extended)
• Service: nodejs/src/services/brain.js

User Story / Use Case

As a company manager, I want to permanently delete all soft-deleted brains under my account so that I can clean up unused data in compliance with company retention policies.

As a regular user, I should not be able to trigger this destructive operation without explicit authorization.

Proposed Solution

1. Route-Level Authorization

   • Extend the route to include role/permission checks using the existing descriptor approach:

   router.delete('/deleteall', authentication, checkPermission('brain.delete_all'), brainController.deleteAllBrain);

2. Controller-Level Defense

   • Add a backup role/permission check in brainController.deleteAllBrain to enforce defense-in-depth.

3. Operational Safeguards

   • Rate Limiting: Limit bulk deletion calls per user/time window.
   • Audit Logging: Log all bulk delete attempts (success/failure) for compliance and monitoring.
   • Feature Flag: Allow toggling this endpoint on/off per environment.
   • Request Validation: Require explicit confirmation (e.g., confirm=true param) to prevent accidental deletions.

Wireframes / Mockups (if any)

N/A - backend-only feature (API-level change).

Acceptance Criteria

• Only COMPANY or MANAGER roles can call DELETE /web/brains/deleteall.
• Regular authenticated users cannot access this endpoint (returns 403 Forbidden).
• Audit logs capture who initiated the delete and when.
• Rate limiting is enforced for bulk deletes.
• Endpoint can be disabled with a feature flag.

Impact

• Security: Prevents unauthorized destructive operations.
• Compliance: Aligns with least-privilege principles.
• Reliability: Defense-in-depth ensures resilience against misconfigurations.
• Operational Safety: Ability to disable or monitor high-risk operations in production.

Alternatives Considered

• Removing the endpoint entirely (but this reduces operational flexibility).
• Relying only on UI-level controls (insufficient, as API is still directly callable).

Additional Notes

• Implementation should align with existing authorization patterns (descriptor approach).
• Consider expanding the solution as part of a broader security hardening effort across all destructive endpoints.

More details

This is an example feature.

Which components are impacted by your request?

No response

Pictures

No response

Code of Conduct

• I agree to follow this project's Code of Conduct