Add documentation and testing tools for JIRA proxy implementation

Co-authored-by: phrocker <[email protected]>

Author: Copilot

llm-proxy/JIRA_PROXY_API.md

@@ -0,0 +1,163 @@
+# JIRA Proxy API Documentation
+
+The JIRA Proxy Controller provides a secure interface to interact with JIRA instances through the Sentrius platform. It mirrors key JIRA REST API endpoints while maintaining the platform's authentication and authorization mechanisms.
+
+## Overview
+
+The JIRA proxy is implemented in the `llm-proxy` module and provides authenticated access to JIRA functionality for agents and compliance tools. It follows the same security patterns as the existing OpenAI proxy.
+
+## Authentication
+
+All endpoints require:
+- Valid JWT token in the `Authorization` header (format: `Bearer <token>`)
+- User must have `CAN_LOG_IN` application access
+- At least one JIRA integration must be configured in the system
+
+## Endpoints
+
+### 1. Search Issues
+
+**GET** `/api/v1/jira/rest/api/3/search`
+
+Search for JIRA issues using JQL or simple text queries.
+
+**Parameters:**
+- `jql` (optional): JIRA Query Language string
+- `query` (optional): Simple text search query
+
+**Example:**
+```bash
+curl -X GET \
+  "https://your-instance/api/v1/jira/rest/api/3/search?query=bug" \
+  -H "Authorization: Bearer <jwt-token>"
+```
+
+**Response:** Array of TicketDTO objects containing issue information.
+
+### 2. Get Issue
+
+**GET** `/api/v1/jira/rest/api/3/issue/{issueKey}`
+
+Retrieve information about a specific JIRA issue.
+
+**Parameters:**
+- `issueKey` (path): JIRA issue key (e.g., "PROJECT-123")
+
+**Example:**
+```bash
+curl -X GET \
+  "https://your-instance/api/v1/jira/rest/api/3/issue/PROJECT-123" \
+  -H "Authorization: Bearer <jwt-token>"
+```
+
+**Response:** Issue status information.
+
+### 3. Add Comment
+
+**POST** `/api/v1/jira/rest/api/3/issue/{issueKey}/comment`
+
+Add a comment to a JIRA issue.
+
+**Parameters:**
+- `issueKey` (path): JIRA issue key
+- Request body: Comment object with `text` or `body` field
+
+**Example:**
+```bash
+curl -X POST \
+  "https://your-instance/api/v1/jira/rest/api/3/issue/PROJECT-123/comment" \
+  -H "Authorization: Bearer <jwt-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "This is a comment from the compliance agent"}'
+```
+
+**Response:** Success/failure message.
+
+### 4. Assign Issue
+
+**PUT** `/api/v1/jira/rest/api/3/issue/{issueKey}/assignee`
+
+Assign a JIRA issue to a user.
+
+**Parameters:**
+- `issueKey` (path): JIRA issue key
+- Request body: Assignee object with `accountId` field
+
+**Example:**
+```bash
+curl -X PUT \
+  "https://your-instance/api/v1/jira/rest/api/3/issue/PROJECT-123/assignee" \
+  -H "Authorization: Bearer <jwt-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"accountId": "user-account-id"}'
+```
+
+**Response:** HTTP 204 (No Content) on success.
+
+## Configuration
+
+### JIRA Integration Setup
+
+Before using the proxy, ensure a JIRA integration is configured:
+
+1. Use the existing `/api/v1/integrations/jira/add` endpoint to add JIRA integration
+2. Provide required fields: `baseUrl`, `username`, `apiToken`
+
+### Security Model
+
+The proxy uses the existing security infrastructure:
+- JWT validation through Keycloak
+- User authentication via `BaseController.getOperatingUser()`
+- Access control through `@LimitAccess` annotations
+- OpenTelemetry tracing for monitoring
+
+## Implementation Details
+
+### Error Handling
+
+- **401 Unauthorized**: Invalid or missing JWT token
+- **404 Not Found**: No JIRA integration configured
+- **400 Bad Request**: Missing required parameters
+- **500 Internal Server Error**: JIRA operation failed
+
+### Integration Token Selection
+
+Currently, the proxy uses the first available JIRA integration found for the connection type "jira". In production environments, you may want to extend this to allow users to specify which integration to use.
+
+### Tracing
+
+All operations are traced using OpenTelemetry with the tracer name `io.sentrius.sso`. Trace spans include:
+- Operation type (search, get-issue, add-comment, assign-issue)
+- Query parameters
+- Result counts
+- Success/failure status
+
+## Future Enhancements
+
+1. **Multi-integration Support**: Allow specifying which JIRA instance to use
+2. **Enhanced JQL Support**: Full JQL query validation and optimization
+3. **Bulk Operations**: Support for bulk issue updates and assignments
+4. **Webhook Support**: Real-time notifications from JIRA
+5. **Custom Field Support**: Access to JIRA custom fields
+6. **Project-specific Operations**: Project creation, configuration management
+
+## Usage with Compliance Agents
+
+This proxy is designed to support compliance agents that need to:
+- Search for compliance-related issues
+- Create comments with compliance findings
+- Assign issues to appropriate team members
+- Track compliance status across JIRA projects
+
+Example agent workflow:
+1. Search for open compliance issues: `GET /api/v1/jira/rest/api/3/search?jql=project = COMPLIANCE AND status = Open`
+2. Add compliance assessment: `POST /api/v1/jira/rest/api/3/issue/COMPLIANCE-123/comment`
+3. Assign for remediation: `PUT /api/v1/jira/rest/api/3/issue/COMPLIANCE-123/assignee`
+
+## Testing
+
+Comprehensive test coverage is provided in `JiraProxyControllerTest.java`, including:
+- Authentication validation
+- Authorization checks
+- Error handling scenarios
+- Request/response validation

llm-proxy/test-jira-proxy.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# JIRA Proxy API Test Script
+# This script demonstrates how to interact with the JIRA proxy endpoints
+
+# Configuration
+BASE_URL="http://localhost:8080"
+JWT_TOKEN="your-jwt-token-here"
+
+echo "Testing JIRA Proxy API Endpoints"
+echo "================================="
+
+# Test 1: Search for issues
+echo -e "\n1. Testing search endpoint..."
+curl -X GET \
+  "${BASE_URL}/api/v1/jira/rest/api/3/search?query=test" \
+  -H "Authorization: Bearer ${JWT_TOKEN}" \
+  -H "Content-Type: application/json" \
+  --silent --show-error || echo "Search test failed (expected if no auth)"
+
+# Test 2: Get specific issue
+echo -e "\n2. Testing get issue endpoint..."
+curl -X GET \
+  "${BASE_URL}/api/v1/jira/rest/api/3/issue/TEST-123" \
+  -H "Authorization: Bearer ${JWT_TOKEN}" \
+  -H "Content-Type: application/json" \
+  --silent --show-error || echo "Get issue test failed (expected if no auth)"
+
+# Test 3: Add comment
+echo -e "\n3. Testing add comment endpoint..."
+curl -X POST \
+  "${BASE_URL}/api/v1/jira/rest/api/3/issue/TEST-123/comment" \
+  -H "Authorization: Bearer ${JWT_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Test comment from compliance agent"}' \
+  --silent --show-error || echo "Add comment test failed (expected if no auth)"
+
+# Test 4: Assign issue
+echo -e "\n4. Testing assign issue endpoint..."
+curl -X PUT \
+  "${BASE_URL}/api/v1/jira/rest/api/3/issue/TEST-123/assignee" \
+  -H "Authorization: Bearer ${JWT_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"accountId": "test-user-id"}' \
+  --silent --show-error || echo "Assign issue test failed (expected if no auth)"
+
+echo -e "\n\nAPI endpoint testing completed."
+echo "Note: These tests will fail with authentication errors unless you have:"
+echo "1. A running instance of the llm-proxy service"
+echo "2. A valid JWT token"
+echo "3. A configured JIRA integration"
+
+# Test with invalid token to verify security
+echo -e "\nTesting security with invalid token..."
+curl -X GET \
+  "${BASE_URL}/api/v1/jira/rest/api/3/search?query=test" \
+  -H "Authorization: Bearer invalid-token" \
+  -H "Content-Type: application/json" \
+  --include --silent --show-error | head -1
+
+echo -e "\nExpected: HTTP 401 Unauthorized for invalid token"