fix: updated lib/src/services/jwt_auth_token_service.dart to correctly serialize the UserRole enum in the JWT payload. This change addresses the JWTException seen in the server logs for the /api/v1/auth/anonymous and /api/v1/auth/verify-code routes

Author: fulleni

lib/src/middlewares/authorization_middleware.dart

@@ -0,0 +1,92 @@
+import 'package:dart_frog/dart_frog.dart';
+import 'package:ht_api/src/rbac/permission_service.dart';
+import 'package:ht_api/src/registry/model_registry.dart';
+import 'package:ht_shared/ht_shared.dart'; // For User, ForbiddenException
+
+/// {@template authorization_middleware}
+/// Middleware to enforce role-based permissions and model-specific access rules.
+///
+/// This middleware reads the authenticated [User], the requested `modelName`,
+/// the `HttpMethod`, and the `ModelConfig` from the request context. It then
+/// determines the required permission based on the `ModelConfig` metadata for
+/// the specific HTTP method and checks if the authenticated user has that
+/// permission using the [PermissionService].
+///
+/// If the user does not have the required permission, it throws a
+/// [ForbiddenException], which should be caught by the [errorHandler] middleware.
+///
+/// This middleware runs *after* authentication and model validation.
+/// It does NOT perform instance-level ownership checks; those are handled
+/// by the route handlers (`index.dart`, `[id].dart`) if required by the
+/// `ModelActionPermission.requiresOwnershipCheck` flag.
+/// {@endtemplate}
+Middleware authorizationMiddleware() {
+  return (handler) {
+    return (context) async {
+      // Read dependencies from the context.
+      // User is guaranteed non-null by requireAuthentication() middleware.
+      final user = context.read<User>();
+      final permissionService = context.read<PermissionService>();
+      final modelName = context.read<String>(); // Provided by data/_middleware
+      final modelConfig = context.read<ModelConfig<dynamic>>(); // Provided by data/_middleware
+      final method = context.request.method;
+
+      // Determine the required permission configuration based on the HTTP method
+      ModelActionPermission requiredPermissionConfig;
+      switch (method) {
+        case HttpMethod.get:
+          requiredPermissionConfig = modelConfig.getPermission;
+        case HttpMethod.post:
+          requiredPermissionConfig = modelConfig.postPermission;
+        case HttpMethod.put:
+          requiredPermissionConfig = modelConfig.putPermission;
+        case HttpMethod.delete:
+          requiredPermissionConfig = modelConfig.deletePermission;
+        default:
+          // Should ideally be caught earlier by Dart Frog's routing,
+          // but as a safeguard, deny unsupported methods.
+          throw const ForbiddenException('Method not supported for this resource.');
+      }
+
+      // Perform the permission check based on the configuration type
+      switch (requiredPermissionConfig.type) {
+        case RequiredPermissionType.none:
+          // No specific permission required (beyond authentication if applicable)
+          // This case is primarily for documentation/completeness if a route
+          // group didn't require authentication, but the /data route does.
+          // For the /data route, 'none' effectively means 'authenticated users allowed'.
+          break;
+        case RequiredPermissionType.adminOnly:
+          // Requires the user to be an admin
+          if (!permissionService.isAdmin(user)) {
+            throw const ForbiddenException(
+              'Only administrators can perform this action.',
+            );
+          }
+        case RequiredPermissionType.specificPermission:
+          // Requires a specific permission string
+          final permission = requiredPermissionConfig.permission;
+          if (permission == null) {
+             // This indicates a configuration error in ModelRegistry
+             print(
+              '[AuthorizationMiddleware] Configuration Error: specificPermission '
+              'type requires a permission string for model "$modelName", method "$method".',
+            );
+            throw const OperationFailedException(
+              'Internal Server Error: Authorization configuration error.',
+            );
+          }
+          if (!permissionService.hasPermission(user, permission)) {
+            throw const ForbiddenException(
+              'You do not have permission to perform this action.',
+            );
+          }
+      }
+
+      // If all checks pass, proceed to the next handler in the chain.
+      // Instance-level ownership checks (if requiredPermissionConfig.requiresOwnershipCheck is true)
+      // are handled by the route handlers themselves.
+      return handler(context);
+    };
+  };
+}

lib/src/rbac/permission_service.dart

@@ -0,0 +1,41 @@
+import 'package:ht_api/src/rbac/role_permissions.dart';
+import 'package:ht_shared/ht_shared.dart';
+
+/// {@template permission_service}
+/// Service responsible for checking if a user has a specific permission.
+///
+/// This service uses the predefined [rolePermissions] map to determine
+/// a user's access rights based on their [UserRole]. It also includes
+/// an explicit check for the [UserRole.admin], granting them all permissions.
+/// {@endtemplate}
+class PermissionService {
+  /// {@macro permission_service}
+  const PermissionService();
+
+  /// Checks if the given [user] has the specified [permission].
+  ///
+  /// Returns `true` if the user's role grants the permission, or if the user
+  /// is an administrator. Returns `false` otherwise.
+  ///
+  /// - [user]: The authenticated user.
+  /// - [permission]: The permission string to check (e.g., `headline.read`).
+  bool hasPermission(User user, String permission) {
+    // Administrators have all permissions
+    if (user.role == UserRole.admin) {
+      return true;
+    }
+
+    // Check if the user's role is in the map and has the permission
+    return rolePermissions[user.role]?.contains(permission) ?? false;
+  }
+
+  /// Checks if the given [user] has the [UserRole.admin] role.
+  ///
+  /// This is a convenience method for checks that are strictly limited
+  /// to administrators, bypassing the permission map.
+  ///
+  /// - [user]: The authenticated user.
+  bool isAdmin(User user) {
+    return user.role == UserRole.admin;
+  }
+}

lib/src/rbac/permissions.dart

@@ -0,0 +1,54 @@
+// ignore_for_file: public_member_api_docs
+
+/// Defines the available permissions in the system.
+///
+/// Permissions follow the format `resource.action`.
+abstract class Permissions {
+  // Headline Permissions
+  static const String headlineCreate = 'headline.create';
+  static const String headlineRead = 'headline.read';
+  static const String headlineUpdate = 'headline.update';
+  static const String headlineDelete = 'headline.delete';
+
+  // Category Permissions
+  static const String categoryCreate = 'category.create';
+  static const String categoryRead = 'category.read';
+  static const String categoryUpdate = 'category.update';
+  static const String categoryDelete = 'category.delete';
+
+  // Source Permissions
+  static const String sourceCreate = 'source.create';
+  static const String sourceRead = 'source.read';
+  static const String sourceUpdate = 'source.update';
+  static const String sourceDelete = 'source.delete';
+
+  // Country Permissions
+  static const String countryCreate = 'country.create';
+  static const String countryRead = 'country.read';
+  static const String countryUpdate = 'country.update';
+  static const String countryDelete = 'country.delete';
+
+  // User Permissions
+  // Allows reading any user profile (e.g., for admin or public profiles)
+  static const String userRead = 'user.read';
+  // Allows reading the authenticated user's own profile
+  static const String userReadOwned = 'user.read_owned';
+  // Allows updating the authenticated user's own profile
+  static const String userUpdateOwned = 'user.update_owned';
+  // Allows deleting the authenticated user's own account
+  static const String userDeleteOwned = 'user.delete_owned';
+
+  // App Settings Permissions (User-owned)
+  static const String appSettingsReadOwned = 'app_settings.read_owned';
+  static const String appSettingsUpdateOwned = 'app_settings.update_owned';
+
+  // User Preferences Permissions (User-owned)
+  static const String userPreferencesReadOwned = 'user_preferences.read_owned';
+  static const String userPreferencesUpdateOwned = 'user_preferences.update_owned';
+
+  // Remote Config Permissions (Admin-owned/managed)
+  static const String remoteConfigReadAdmin = 'remote_config.read_admin';
+  static const String remoteConfigUpdateAdmin = 'remote_config.update_admin';
+
+  // Add other permissions as needed for future models/features
+}

lib/src/rbac/role_permissions.dart

@@ -0,0 +1,72 @@
+import 'package:ht_api/src/rbac/permission_service.dart' show PermissionService;
+import 'package:ht_api/src/rbac/permissions.dart';
+import 'package:ht_shared/ht_shared.dart'; // Assuming UserRole is defined here
+
+/// Defines the mapping between user roles and the permissions they possess.
+///
+/// This map is the core of the Role-Based Access Control (RBAC) system.
+/// Each key is a [UserRole], and the associated value is a [Set] of
+/// [Permissions] strings that users with that role are granted.
+///
+/// Note: Administrators typically have implicit access to all resources
+/// regardless of this map, but including their permissions here can aid
+/// documentation and clarity. The [PermissionService] should handle the
+/// explicit admin bypass if desired.
+final Map<UserRole, Set<String>> rolePermissions = {
+  UserRole.admin: {
+    // Admins typically have all permissions. Listing them explicitly
+    // or handling the admin bypass in PermissionService are options.
+    // For clarity, listing some key admin permissions here:
+    Permissions.headlineCreate,
+    Permissions.headlineRead,
+    Permissions.headlineUpdate,
+    Permissions.headlineDelete,
+    Permissions.categoryCreate,
+    Permissions.categoryRead,
+    Permissions.categoryUpdate,
+    Permissions.categoryDelete,
+    Permissions.sourceCreate,
+    Permissions.sourceRead,
+    Permissions.sourceUpdate,
+    Permissions.sourceDelete,
+    Permissions.countryCreate,
+    Permissions.countryRead,
+    Permissions.countryUpdate,
+    Permissions.countryDelete,
+    Permissions.userRead, // Admins can read any user profile
+    Permissions.userReadOwned,
+    Permissions.userUpdateOwned,
+    Permissions.userDeleteOwned,
+    Permissions.appSettingsReadOwned,
+    Permissions.appSettingsUpdateOwned,
+    Permissions.userPreferencesReadOwned,
+    Permissions.userPreferencesUpdateOwned,
+    Permissions.remoteConfigReadAdmin,
+    Permissions.remoteConfigUpdateAdmin,
+    // Add all other permissions here for completeness if not using admin bypass
+  },
+  UserRole.standardUser: {
+    // Standard users can read public/shared data
+    Permissions.headlineRead,
+    Permissions.categoryRead,
+    Permissions.sourceRead,
+    Permissions.countryRead,
+    // Standard users can manage their own user-owned data
+    Permissions.userReadOwned,
+    Permissions.userUpdateOwned,
+    Permissions.userDeleteOwned,
+    Permissions.appSettingsReadOwned,
+    Permissions.appSettingsUpdateOwned,
+    Permissions.userPreferencesReadOwned,
+    Permissions.userPreferencesUpdateOwned,
+    // Add other permissions for standard users as needed
+  },
+  UserRole.guestUser: {
+    // Guest users have very limited permissions, primarily reading public data
+    Permissions.headlineRead,
+    Permissions.categoryRead,
+    Permissions.sourceRead,
+    Permissions.countryRead,
+    // Add other permissions for guest users as needed
+  },
+};