[RFC] Centralized Role-Based Access Control (RBAC) System

## Summary

I propose we implement a centralized **Role-Based Access Control (RBAC)** architecture for the Petition Platform. By moving from ad-hoc authorization checks to a unified middleware model, we will align the platform with OWASP security standards and resolve systemic vulnerabilities I have identified in our API.

## Motivation

I recently conducted a security audit of the platform and found that our current authorization model is decentralized and brittle. This has resulted in several architectural risks:

- **Broken Access Control:** No standard mechanism exists to distinguish "Admins" from regular "Users".
- **Insecure Direct Object References (IDOR):** Ownership verification is inconsistent across endpoints.
- **Maintenance Overhead:** Developers must manually implement security logic for every new route, increasing the risk of human error.

## Guide-Level Explanation

We will introduce a **Privilege Guard** pattern.

Currently, developers might write code like this:

```typescript
// functions/api/admin/reports.ts
if (!user) {
return createCachedErrorResponse('Authentication required', context.request, context.env, 401)
}
// TODO: Add admin role check here when roles are implemented
```

With this proposal, developers **MUST** use the standard guard:

```typescript
import { requirePermission } from '@api/_shared/utils'

export const onRequest = async context => {
const auth = await requirePermission(context, 'admin')
if (auth instanceof Response) return auth

// Business logic...
}
```

## Proposed Design

### Database Schema

The `users` table **MUST** include a strict role definition.

```sql
ALTER TABLE users ADD COLUMN role TEXT DEFAULT 'user'
CHECK(role IN ('user', 'admin', 'moderator'));
```

### Middleware Architecture

We will implement a `requirePermission` utility in `functions/_shared/utils.ts`. This middleware **SHOULD**:

1. Verify the session token.
2. Check the `role` claim against the required permission.
3. Log any unauthorized access attempts.

### Session Management

To ensure performance, the User Role **SHOULD** be embedded in the Auth.js session token, preventing the need for a database lookup on every API request.

## Security Considerations

This architecture is designed to mitigate the following specific risks identified during audit:

- [ ] **Admin Endpoint Vulnerability:** Unauthorized access to `/api/admin/*`.
- [ ] **User Data IDOR:** Unauthorized access to `/api/users/*`.
- [ ] **Privilege Escalation:** Prevention of unauthorized role changes.

_(Note: Detailed tracking issues for these specific findings will be linked here upon acceptance of this RFC.)_

**Alternatives**: We could continue patching individual files, but this leaves the systemic risk unaddressed.

## Drawbacks

- Requires a database migration on the `users` table.
- Existing endpoints (like `/api/admin/reports`) must be refactored to use the new guard, which incurs development time.
- Storing roles in the session token means that if a user's role is revoked, they may retain access until their session expires (unless we implement a revocation check).

## References

- [OWASP Top 10:2021 A01](https://owasp.org/Top10/A01_2021-Broken_Access_Control/): Broken Access Control.
- [OWASP ASVS 4.0](https://owasp.org/www-project-application-security-verification-standard/): V4 Access Control Verification Requirements.
- [NIST SP 800-53](https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final): Access Control Guidelines (AC-3).
- [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html): Deny-by-default principles.
- [CWE-862](https://cwe.mitre.org/data/definitions/862.html): Missing Authorization.
- [Auth.js Session Callbacks](https://authjs.dev/reference/core/types#session): Technical reference for implementation.
- [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt): Key words for use in RFCs to Indicate Requirement Levels.

---

Start by reading functions/api/admin/reports.ts and functions/_shared/utils.ts to understand the existing authentication flow, then inspect the users schema and Auth.js session callbacks. The proposal calls for a role migration, centralized permission checks, session-role handling, logging, and endpoint refactoring, but says detailed tracking issues will be added later, so the acceptance criteria are not yet complete.

Written by the indexing model from the issue text.