chore: Enforce custom role permissions on conversation access (#12583)

## Summary
- ensure conversation lookup uses the permission filter before fetching
records
- add request specs covering custom role access to unassigned
conversations

## Testing
- bundle exec rspec
spec/enterprise/controllers/api/v1/accounts/conversations_controller_spec.rb

------
https://chatgpt.com/codex/tasks/task_e_68de1f62b9b883268a54882e608a8bb8

spec/enterprise/controllers/api/v1/accounts/conversations_controller_spec.rb

@@ -30,5 +30,76 @@ RSpec.describe 'Conversations API', type: :request do
       expect(response.parsed_body.keys).not_to include('applied_sla')
       expect(response.parsed_body.keys).not_to include('sla_events')
     end
+
+    context 'when agent has team access' do
+      let(:agent) { create(:user, account: account, role: :agent) }
+      let(:team) { create(:team, account: account) }
+      let(:conversation) { create(:conversation, account: account, team: team) }
+
+      before do
+        create(:team_member, team: team, user: agent)
+      end
+
+      it 'allows accessing the conversation via team membership' do
+        get "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}", headers: agent.create_new_auth_token
+
+        expect(response).to have_http_status(:ok)
+        expect(response.parsed_body['id']).to eq(conversation.display_id)
+      end
+    end
+
+    context 'when agent has a custom role' do
+      let(:agent) { create(:user, account: account, role: :agent) }
+      let(:conversation) { create(:conversation, account: account) }
+
+      before do
+        create(:inbox_member, user: agent, inbox: conversation.inbox)
+      end
+
+      it 'returns unauthorized for unassigned conversation without permission' do
+        custom_role = create(:custom_role, account: account, permissions: ['conversation_participating_manage'])
+        account.account_users.find_by(user_id: agent.id).update!(custom_role: custom_role)
+
+        get "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}", headers: agent.create_new_auth_token
+
+        expect(response).to have_http_status(:unauthorized)
+      end
+
+      it 'returns the conversation when permission allows managing unassigned conversations, including when assigned to agent' do
+        custom_role = create(:custom_role, account: account, permissions: ['conversation_unassigned_manage'])
+        account_user = account.account_users.find_by(user_id: agent.id)
+        account_user.update!(custom_role: custom_role)
+        conversation.update!(assignee: agent)
+
+        get "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}", headers: agent.create_new_auth_token
+
+        expect(response).to have_http_status(:ok)
+        expect(response.parsed_body['id']).to eq(conversation.display_id)
+      end
+
+      it 'returns the conversation when permission allows managing assigned conversations' do
+        custom_role = create(:custom_role, account: account, permissions: ['conversation_participating_manage'])
+        account_user = account.account_users.find_by(user_id: agent.id)
+        account_user.update!(custom_role: custom_role)
+        conversation.update!(assignee: agent)
+
+        get "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}", headers: agent.create_new_auth_token
+
+        expect(response).to have_http_status(:ok)
+        expect(response.parsed_body['id']).to eq(conversation.display_id)
+      end
+
+      it 'returns the conversation when permission allows managing participating conversations' do
+        custom_role = create(:custom_role, account: account, permissions: ['conversation_participating_manage'])
+        account_user = account.account_users.find_by(user_id: agent.id)
+        account_user.update!(custom_role: custom_role)
+        create(:conversation_participant, conversation: conversation, account: account, user: agent)
+
+        get "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}", headers: agent.create_new_auth_token
+
+        expect(response).to have_http_status(:ok)
+        expect(response.parsed_body['id']).to eq(conversation.display_id)
+      end
+    end
   end
 end

spec/enterprise/policies/conversation_policy_spec.rb

@@ -0,0 +1,65 @@
+require 'rails_helper'
+
+RSpec.describe ConversationPolicy, type: :policy do
+  subject { described_class }
+
+  let(:account) { create(:account) }
+  let(:agent) { create(:user, account: account, role: :agent) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:agent_account_user) { agent.account_users.find_by(account: account) }
+  let(:context) { { user: agent, account: account, account_user: agent_account_user } }
+
+  before do
+    create(:inbox_member, user: agent, inbox: inbox)
+  end
+
+  permissions :show? do
+    context 'when role grants conversation_unassigned_manage' do
+      let(:custom_role) { create(:custom_role, account: account, permissions: ['conversation_unassigned_manage']) }
+
+      before do
+        agent_account_user.update!(role: :agent, custom_role: custom_role)
+      end
+
+      it 'allows access to conversations assigned to the agent' do
+        conversation = create(:conversation, account: account, inbox: inbox, assignee: agent)
+
+        expect(subject).to permit(context, conversation)
+      end
+
+      it 'denies access to conversations assigned to someone else' do
+        other_agent = create(:user, account: account, role: :agent)
+        conversation = create(:conversation, account: account, inbox: inbox, assignee: other_agent)
+
+        expect(subject).not_to permit(context, conversation)
+      end
+    end
+
+    context 'when role grants conversation_participating_manage' do
+      let(:custom_role) { create(:custom_role, account: account, permissions: ['conversation_participating_manage']) }
+
+      before do
+        agent_account_user.update!(role: :agent, custom_role: custom_role)
+      end
+
+      it 'allows access to conversations assigned to the agent' do
+        conversation = create(:conversation, account: account, inbox: inbox, assignee: agent)
+
+        expect(subject).to permit(context, conversation)
+      end
+
+      it 'allows access to conversations where the agent is a participant' do
+        conversation = create(:conversation, account: account, inbox: inbox, assignee: nil)
+        create(:conversation_participant, conversation: conversation, account: account, user: agent)
+
+        expect(subject).to permit(context, conversation)
+      end
+
+      it 'denies access to unrelated conversations' do
+        conversation = create(:conversation, account: account, inbox: inbox, assignee: nil)
+
+        expect(subject).not_to permit(context, conversation)
+      end
+    end
+  end
+end