Pundit Policies

Closes #70

Author: jaspermayone

CLAUDE.md

@@ -67,6 +67,16 @@ A Rails 8 API backend that syncs college course schedules to Google Calendar wit
 - Audit logging with Audits1984 and Console1984
 - Admin access via Google OAuth + access_level enum (user/admin/super_admin/owner)
 
+**Authorization System (Pundit)**
+- Role-based access control via User `access_level`: user/admin/super_admin/owner
+- **user** (0): Can manage their own resources only
+- **admin** (1): VIEW all resources for support, manage public data (courses/faculty), NO destructive actions
+- **super_admin** (2): View AND modify all resources, perform destructive actions, access feature flags. **Cannot delete owners**
+- **owner** (3): Full access including managing other admins
+- Three policy categories: User-Owned (users manage their own), Public-Read (everyone reads, admins manage), Admin-Only (admins view only)
+- All controllers use `authorize @resource` to check permissions via policies in `app/policies/`
+- See `docs/authorization.md` for complete documentation
+
 ### Domain Models
 
 **User & Authentication**
@@ -119,10 +129,11 @@ A Rails 8 API backend that syncs college course schedules to Google Calendar wit
 2. **Always annotate after route changes**: Run `bundle exec annotaterb routes` after modifying routes
 3. **Prefer background jobs**: Use ActiveJob for blocking operations (Google Calendar API calls, web scraping, etc.)
 4. **Full test coverage required**: Write RSpec tests for all new code
-5. **Respect user edits**: The calendar sync intelligently detects and preserves user modifications in Google Calendar
-6. **Template validation**: Calendar preference templates are validated; invalid syntax is rejected
-7. **OAuth token encryption**: All sensitive tokens are encrypted with Lockbox
-8. **Multi-email support**: Design features to support users with multiple connected Google accounts
+5. **Use Pundit authorization**: All controller actions must use `authorize @resource` to check permissions
+6. **Respect user edits**: The calendar sync intelligently detects and preserves user modifications in Google Calendar
+7. **Template validation**: Calendar preference templates are validated; invalid syntax is rejected
+8. **OAuth token encryption**: All sensitive tokens are encrypted with Lockbox
+9. **Multi-email support**: Design features to support users with multiple connected Google accounts
 
 ## Common Development Workflows
 
@@ -145,8 +156,17 @@ A Rails 8 API backend that syncs college course schedules to Google Calendar wit
 3. Add validation tests
 4. Update preview endpoint tests
 
+### Adding Authorization to Controllers
+1. Add `authorize @resource` after finding/creating records
+2. Use `policy_scope(Model)` to filter collections by user permissions
+3. Create corresponding policy in `app/policies/` if it doesn't exist
+4. Write RSpec tests in `spec/policies/` to verify permissions
+5. See `docs/authorization.md` for policy patterns
+
 ### Running Tests for Specific Features
+- Authorization policies: `bundle exec rspec spec/policies/`
 - Calendar preferences: `bundle exec rspec spec/models/calendar_preference_spec.rb`
 - Template rendering: `bundle exec rspec spec/services/calendar_template_renderer_spec.rb`
 - Preference resolution: `bundle exec rspec spec/services/preference_resolver_spec.rb`
 - Google Calendar sync: `bundle exec rspec spec/services/google_calendar_service_spec.rb`
+- always make and follow pundit policies

app/controllers/admin/calendars_controller.rb

@@ -4,7 +4,7 @@ module Admin
   class CalendarsController < Admin::BaseController
     def index
       # Get calendars from the database with associations
-      @calendars = GoogleCalendar
+      @calendars = policy_scope(GoogleCalendar)
                    .includes(:oauth_credential, :user)
                    .left_joins(:google_calendar_events)
                    .select("google_calendars.*, MAX(google_calendar_events.updated_at) as max_event_updated_at")
@@ -24,6 +24,8 @@ def index
 
     def destroy
       calendar = GoogleCalendar.find(params[:id])
+      authorize calendar
+
       # Enqueue job to delete calendar from Google
       GoogleCalendarDeleteJob.perform_later(calendar.google_calendar_id)
       # Delete the database record

app/controllers/admin/courses_controller.rb

@@ -3,7 +3,7 @@
 module Admin
   class CoursesController < Admin::ApplicationController
     def index
-      @courses = Course.includes(:term, :faculty).order(created_at: :desc).page(params[:page])
+      @courses = policy_scope(Course).includes(:term, :faculty).order(created_at: :desc).page(params[:page])
     end
   end
 end

app/controllers/admin/faculties_controller.rb

@@ -3,15 +3,16 @@
 module Admin
   class FacultiesController < Admin::ApplicationController
     def index
-      @faculties = Faculty.order(:last_name, :first_name).page(params[:page])
+      @faculties = policy_scope(Faculty).order(:last_name, :first_name).page(params[:page])
     end
 
     def missing_rmp_ids
-      @faculties = Faculty.where(rmp_id: nil).order(:last_name, :first_name).page(params[:page])
+      @faculties = policy_scope(Faculty).where(rmp_id: nil).order(:last_name, :first_name).page(params[:page])
     end
 
     def search_rmp
       @faculty = Faculty.find(params[:id])
+      authorize @faculty
       service = RateMyProfessorService.new
 
       search_result = service.search_professors(@faculty.full_name, count: 10)
@@ -30,6 +31,8 @@ def search_rmp
 
     def assign_rmp_id
       @faculty = Faculty.find(params[:id])
+      authorize @faculty
+
       rmp_id = params[:rmp_id]
 
       if rmp_id.blank?

app/controllers/admin/users_controller.rb

@@ -7,7 +7,7 @@ class UsersController < Admin::ApplicationController
     BETA_FEATURE_FLAG = FlipperFlags::V1
 
     def index
-      @users = User.order(created_at: :desc)
+      @users = policy_scope(User).order(created_at: :desc)
 
       if params[:search].present?
         @users = @users.where("email ILIKE ?", "%#{params[:search]}%")
@@ -21,6 +21,8 @@ def index
     end
 
     def show
+      authorize @user
+
       # Eager load enrollments with their associations for the view
       @enrollments_by_term = @user.enrollments
                                   .includes(:course, :term)
@@ -38,9 +40,12 @@ def show
     end
 
     def edit
+      authorize @user
     end
 
     def update
+      authorize @user
+
       if @user.update(user_params)
         redirect_to admin_user_path(@user), notice: "User was successfully updated."
       else
@@ -49,12 +54,15 @@ def update
     end
 
     def destroy
+      authorize @user
+
       @user.destroy
       redirect_to admin_users_path, notice: "User was successfully deleted."
     end
 
     def revoke_oauth_credential
       credential = @user.oauth_credentials.find(params[:credential_id])
+      authorize credential
       credential_email = credential.email
 
       # Queue the revocation job
@@ -66,6 +74,8 @@ def revoke_oauth_credential
     end
 
     def enable_beta
+      authorize @user, :update? # Beta management requires update permission
+
       Flipper.enable_actor(BETA_FEATURE_FLAG, @user)
       redirect_to admin_user_path(@user), notice: "#{@user.email} has been added to the beta test group."
     rescue => e
@@ -74,6 +84,8 @@ def enable_beta
     end
 
     def disable_beta
+      authorize @user, :update? # Beta management requires update permission
+
       Flipper.disable_actor(BETA_FEATURE_FLAG, @user)
       redirect_to admin_user_path(@user), notice: "Beta tester access removed for #{@user.email}."
     rescue => e

app/controllers/api/api_controller.rb

@@ -9,5 +9,13 @@ class ApiController < ApplicationController
 
     skip_before_action :verify_authenticity_token
 
+    # Handle Pundit authorization errors with JSON response
+    rescue_from Pundit::NotAuthorizedError, with: :pundit_not_authorized
+
+    private
+
+    def pundit_not_authorized
+      render json: { error: "You are not authorized to perform this action." }, status: :forbidden
+    end
   end
 end

app/controllers/api/calendar_preferences_controller.rb

@@ -6,8 +6,9 @@ class CalendarPreferencesController < ApiController
 
     # GET /api/calendar_preferences
     def index
-      global_pref = current_user.calendar_preferences.find_by(scope: :global)
-      event_type_prefs = current_user.calendar_preferences.where(scope: :event_type)
+      preferences = policy_scope(current_user.calendar_preferences)
+      global_pref = preferences.find_by(scope: :global)
+      event_type_prefs = preferences.where(scope: :event_type)
 
       render json: {
         global: global_pref ? preference_json(global_pref) : nil,
@@ -18,12 +19,14 @@ def index
     # GET /api/calendar_preferences/global
     # GET /api/calendar_preferences/:event_type
     def show
+      authorize @calendar_preference
       render json: preference_json(@calendar_preference)
     end
 
     # PUT /api/calendar_preferences/global
     # PUT /api/calendar_preferences/:event_type
     def update
+      authorize @calendar_preference
       if @calendar_preference.update(calendar_preference_params)
         render json: preference_json(@calendar_preference)
       else
@@ -33,6 +36,7 @@ def update
 
     # DELETE /api/calendar_preferences/:event_type
     def destroy
+      authorize @calendar_preference
       @calendar_preference.destroy
       head :no_content
     end

app/controllers/api/event_preferences_controller.rb

@@ -12,6 +12,9 @@ def show
         preferenceable: @preferenceable
       )
 
+      # Authorize either the existing preference or create a new one to check authorization
+      authorize preference || EventPreference.new(user: current_user, preferenceable: @preferenceable)
+
       # Get resolved preferences with sources
       resolver = PreferenceResolver.new(current_user)
       resolved_data = resolver.resolve_with_sources(@preferenceable)
@@ -40,6 +43,8 @@ def update
         preferenceable: @preferenceable
       )
 
+      authorize preference
+
       if preference.update(event_preference_params)
         render json: event_preference_json(preference)
       else
@@ -56,6 +61,7 @@ def destroy
       )
 
       if preference
+        authorize preference
         preference.destroy
         head :no_content
       else

app/controllers/api/user_extension_config_controller.rb

@@ -4,6 +4,7 @@ module Api
   class UserExtensionConfigController < ApiController
     def set
       config = UserExtensionConfig.find_or_initialize_by(user_id: current_user.id)
+      authorize config
 
       config.military_time = params[:military_time] unless params[:military_time].nil?
       config.default_color_lecture = params[:default_color_lecture] unless params[:default_color_lecture].nil?
@@ -29,6 +30,8 @@ def get
         return
       end
 
+      authorize config
+
       render json: {
         military_time: config.military_time,
         default_color_lecture: config.default_color_lecture,

app/controllers/api/users_controller.rb

@@ -32,6 +32,8 @@ def onboard
     end
 
     def is_processed
+      authorize current_user
+
       term_uid = params[:term_uid]
 
       if term_uid.blank?
@@ -51,6 +53,7 @@ def is_processed
     end
 
     def get_email
+      authorize current_user
 
       email = Email.where(user_id: current_user.id, primary: true).pick(:email)
 
@@ -68,6 +71,7 @@ def add_email_to_g_cal
       email = email.to_s.strip
       # Create/update Email record with g_cal = true
       email_record = current_user.emails.find_or_initialize_by(email: email)
+      authorize email_record
       email_record.g_cal = true
       email_record.save!
 
@@ -111,6 +115,8 @@ def remove_email_from_g_cal
         return
       end
 
+      authorize email_record
+
       # Check if user has a calendar to remove access from
       calendar_id = current_user.google_course_calendar_id
       if calendar_id.blank?
@@ -144,6 +150,7 @@ def request_g_cal
 
       # Create/update Email record with g_cal = true
       email_record = current_user.emails.find_or_initialize_by(email: email)
+      authorize email_record
       email_record.g_cal = true
       email_record.save!
 
@@ -267,12 +274,16 @@ def group_meeting_times(meeting_times)
     end
 
     def get_ics_url
+      authorize current_user
+
       render json: {
         ics_url: current_user.cal_url_with_extension
       }
     end
 
     def get_processed_events_by_term
+      authorize current_user
+
       term_uid = params[:term_uid]
 
       if term_uid.blank?