feat: implement RBAC for access control

- Added permissions and roles
- Created AuthorizationService
- Defined role-permission mapping

Author: fulleni

lib/src/permissions.dart

@@ -0,0 +1,96 @@
+/// Defines the roles and permissions used in the RBAC system.
+///
+/// Permissions are defined as constants in the format `resource.action`.
+/// Roles are defined as constants.
+/// The `rolePermissions` map defines which permissions are granted to each role.
+
+/// {@template role}
+/// Defines the available user roles in the system.
+/// {@endtemplate}
+abstract class Role {
+  /// Administrator role with full access.
+  static const String admin = 'admin';
+
+  /// Standard user role with limited access.
+  static const String standardUser = 'standard_user';
+
+  // Add other roles here as needed.
+}
+
+/// {@template permission}
+/// Defines the available permissions in the system.
+///
+/// Permissions follow the format `resource.action`.
+/// {@endtemplate}
+abstract class Permission {
+  // Headline Permissions
+  static const String headlineRead = 'headline.read';
+  static const String headlineCreate = 'headline.create';
+  static const String headlineUpdate = 'headline.update';
+  static const String headlineDelete = 'headline.delete';
+
+  // Category Permissions
+  static const String categoryRead = 'category.read';
+  static const String categoryCreate = 'category.create';
+  static const String categoryUpdate = 'category.update';
+  static const String categoryDelete = 'category.delete';
+
+  // Source Permissions
+  static const String sourceRead = 'source.read';
+  static const String sourceCreate = 'source.create';
+  static const String sourceUpdate = 'source.update';
+  static const String sourceDelete = 'source.delete';
+
+  // Country Permissions
+  static const String countryRead = 'country.read';
+  static const String countryCreate = 'country.create';
+  static const String countryUpdate = 'country.update';
+  static const String countryDelete = 'country.delete';
+
+  // User Settings Permissions
+  static const String userSettingsRead = 'user_settings.read';
+  static const String userSettingsUpdate = 'user_settings.update';
+  // Note: User settings delete is handled via account deletion, no separate permission needed here.
+
+  // Add other resource permissions here as needed.
+}
+
+/// A map defining which permissions are granted to each role.
+///
+/// The key is the role string, and the value is a set of permission strings.
+final Map<String, Set<String>> rolePermissions = {
+  Role.admin: {
+    // Admins have all permissions. In a real system, you might have a more
+    // sophisticated way to represent this, but listing them explicitly is clear.
+    Permission.headlineRead,
+    Permission.headlineCreate,
+    Permission.headlineUpdate,
+    Permission.headlineDelete,
+    Permission.categoryRead,
+    Permission.categoryCreate,
+    Permission.categoryUpdate,
+    Permission.categoryDelete,
+    Permission.sourceRead,
+    Permission.sourceCreate,
+    Permission.sourceUpdate,
+    Permission.sourceDelete,
+    Permission.countryRead,
+    Permission.countryCreate,
+    Permission.countryUpdate,
+    Permission.countryDelete,
+    Permission.userSettingsRead,
+    Permission.userSettingsUpdate,
+    // Add other admin permissions here.
+  },
+  Role.standardUser: {
+    // Standard users can read public data and manage their own settings.
+    Permission.headlineRead,
+    Permission.categoryRead,
+    Permission.sourceRead,
+    Permission.countryRead,
+    Permission.userSettingsRead, // Can read their own settings
+    Permission.userSettingsUpdate, // Can update their own settings
+    // Add other standard user permissions here.
+  },
+  // Add mappings for other roles here.
+};

lib/src/services/authorization_service.dart

@@ -0,0 +1,35 @@
+import 'package:ht_api/src/permissions.dart';
+import 'package:ht_shared/ht_shared.dart'; // Assuming User model is here
+
+/// {@template authorization_service}
+/// Service responsible for checking user permissions based on roles.
+/// {@endtemplate}
+class AuthorizationService {
+  /// {@macro authorization_service}
+  const AuthorizationService();
+
+  /// Checks if the given [user] has the specified [permission].
+  ///
+  /// Assumes the [User] model has a `role` property (String).
+  /// Returns `true` if the user has the permission, `false` otherwise.
+  bool hasPermission(User user, String permission) {
+    // Admins always have permission.
+    // Assuming user.role exists and 'admin' is the admin role string.
+    if (user.role == Role.admin) {
+      return true;
+    }
+
+    // Get the permissions for the user's role.
+    final permissionsForRole = rolePermissions[user.role];
+
+    // If the role is not found or has no permissions, deny access.
+    if (permissionsForRole == null) {
+      return false;
+    }
+
+    // Check if the requested permission is in the set of permissions for the role.
+    return permissionsForRole.contains(permission);
+  }
+
+  // Optional: Add methods for checking ownership or other complex authorization rules here later.
+}

rbac-plan.dart

@@ -0,0 +1,51 @@
+/// High-Level Plan for Implementing Role-Based Access Control (RBAC)
+/// in the Headlines Toolkit API (ht-api).
+///
+/// This plan outlines the key tasks required to transition from the basic
+/// ModelOwnership approach to a more flexible RBAC system, tailored to the
+/// project's existing architecture and shared packages.
+///
+/// This is a high-level overview and does not include implementation details.
+
+// Assuming the User model in ht_shared has been updated to include a 'role' property.
+
+// 1. Define Roles and Permissions (Initially within ht_api)
+//    - Determine the specific roles needed (e.g., admin, standard_user, editor).
+//    - Define granular permissions for each resource and action (e.g., 'headline.read',
+//      'category.create', 'user_settings.update', 'favorite_list.add').
+//    - Store these permission strings as static constants within the ht_api package
+//      (e.g., in a new file like lib/src/permissions.dart).
+//    - Map which permissions are assigned to which roles (e.g., using a Map or class
+//      within ht_api).
+
+// 2. Create Authorization Service (Within ht_api)
+//    - Implement a dedicated service (e.g., AuthorizationService in lib/src/services/)
+//      that encapsulates the logic for checking permissions.
+//    - This service will take an authenticated User object and a requested permission
+//      string, and determine if the user's role(s) grant them that permission based
+//      on the hardcoded role-permission mapping.
+
+// 3. Integrate Authorization Checks into Middleware/Routes
+//    - Modify the /api/v1/data/_middleware.dart to check permissions based on
+//      the requested model and HTTP method using the new AuthorizationService.
+//      (e.g., check for 'modelName.read' for GET, 'modelName.create' for POST).
+//    - For user-owned resources (like settings or future favorite lists), update
+//      middleware (e.g., routes/api/v1/users/[userId]/settings/_middleware.dart)
+//      or handlers to combine the permission check (e.g., 'user_settings.update')
+//      with the ownership check (authenticated user ID matches resource owner ID,
+//      unless user is admin).
+
+// 4. Refine Ownership Checks (Within ht_api middleware/handlers or Repositories)
+//    - For user-owned resources, ensure repository methods accept the authenticated
+//      userId and enforce that operations are limited to resources owned by that user
+//      (unless the user is an admin). This pattern is already partially used and
+//      can be consistently applied.
+
+// 5. Refactor Existing Access Control
+//    - Replace existing basic isAdmin checks and simple ownership comparisons
+//      in route handlers with calls to the new AuthorizationService and/or rely
+//      on the updated middleware/repository checks.
+
+// 6. Add Tests
+//    - Write unit and integration tests for the new AuthorizationService, middleware,
+//      and affected route handlers to ensure permissions and ownership are enforced correctly.