cve-dashboard/.kiro/specs/jira-api-compliance-cleanup/requirements.md

Requirements Document

Introduction

The STEAM Security Dashboard integrates with Charter's Jira Data Center via a service account. A service account approval request (ATLSUP ticket) was submitted and the reviewer identified two compliance issues that must be resolved before production approval:

1. The POST /api/jira/search Express route accepts arbitrary JQL from the frontend and proxies it to POST /rest/api/2/search, which is not an approved Jira API pattern. This endpoint must be removed entirely — the dashboard's actual workflows (create, sync, lookup) are already served by other endpoints.
2. The searchIssuesByKeys() bulk-sync function uses updated >= -24h in its JQL, but the team works Monday–Friday, meaning the worst-case gap between syncs is Friday evening to Monday morning (~60 hours). The window must be widened to -72h to cover weekends.
3. The API use-cases documentation (jira-api-use-cases.md) must be updated to reflect both changes so the compliance summary remains accurate for the ATLSUP reviewer.

Glossary

• Dashboard: The STEAM Security Dashboard Node.js/Express backend application
• Search_Route: The POST /api/jira/search Express route in backend/routes/jiraTickets.js that accepts arbitrary JQL from the frontend
• SearchIssuesByKeys_Function: The searchIssuesByKeys() helper function in backend/helpers/jiraApi.js used by the bulk sync-all flow
• SearchIssues_Function: The searchIssues() helper function in backend/helpers/jiraApi.js that executes JQL queries via GET /rest/api/2/search
• Sync_All_Route: The POST /api/jira/sync-all Express route that bulk-refreshes all tracked Jira tickets
• JQL_Window: The updated >= -Xh clause appended to JQL queries to limit results to recently-changed issues
• API_Documentation: The file docs/api/jira-api-use-cases.md that documents all Jira API use cases for the ATLSUP reviewer
• Compliance_Summary_Table: The table in the API_Documentation that summarizes Charter compliance posture

Requirements

Requirement 1: Remove the arbitrary JQL search route

User Story: As a service account reviewer, I want the dashboard to not expose an arbitrary JQL search endpoint, so that the integration only uses approved Jira API patterns.

Acceptance Criteria

1. WHEN the Dashboard starts, THE Dashboard SHALL NOT register a POST /api/jira/search route
2. WHEN a client sends a POST request to /api/jira/search, THE Dashboard SHALL respond with HTTP 404
3. WHILE the Search_Route is removed, THE Sync_All_Route SHALL continue to function by calling the SearchIssuesByKeys_Function
4. WHILE the Search_Route is removed, THE Dashboard SHALL continue to support single-ticket lookup via GET /api/jira/lookup/:issueKey
5. WHILE the Search_Route is removed, THE Dashboard SHALL continue to support single-ticket sync via POST /api/jira/:id/sync
6. WHILE the Search_Route is removed, THE Dashboard SHALL continue to support ticket creation via POST /api/jira/create-in-jira

Requirement 2: Widen the bulk-sync JQL time window to 72 hours

User Story: As a dashboard administrator, I want the bulk sync to use a 72-hour JQL window, so that tickets updated over the weekend are captured on Monday morning.

Acceptance Criteria

1. WHEN the SearchIssuesByKeys_Function builds a JQL query, THE SearchIssuesByKeys_Function SHALL include the clause updated >= -72h instead of updated >= -24h
2. WHEN the Sync_All_Route processes a batch of ticket keys, THE Sync_All_Route SHALL receive results that include tickets updated within the last 72 hours
3. WHILE the JQL_Window is set to 72 hours, THE SearchIssuesByKeys_Function SHALL continue to include the project = <KEY> clause in the JQL query
4. WHILE the JQL_Window is set to 72 hours, THE SearchIssuesByKeys_Function SHALL continue to cap maxResults at 1000

Requirement 3: Update the API use-cases documentation

User Story: As a service account reviewer, I want the API documentation to accurately reflect the dashboard's current Jira API usage, so that the ATLSUP approval can proceed without discrepancies.

Acceptance Criteria

1. WHEN the API_Documentation is updated, THE API_Documentation SHALL NOT contain a use case entry for POST /api/jira/search or arbitrary JQL search
2. WHEN the API_Documentation is updated, THE API_Documentation SHALL show the JQL pattern for the bulk sync use case as updated >= -72h instead of updated >= -24h
3. WHEN the API_Documentation is updated, THE Compliance_Summary_Table SHALL accurately reflect that all JQL queries use scoped, predefined patterns with no arbitrary JQL passthrough
4. WHEN the API_Documentation is updated, THE API_Documentation SHALL update the estimated daily API usage table to remove the row for the arbitrary JQL search endpoint
5. WHEN the API_Documentation is updated, THE API_Documentation SHALL update the total estimated daily API call range to reflect the removal of the search endpoint

Requirement 4: Preserve the internal searchIssues helper for scoped callers

User Story: As a developer, I want the internal searchIssues() helper to remain available for use by getIssue() and searchIssuesByKeys(), so that existing scoped JQL operations continue to work.

Acceptance Criteria

1. WHILE the Search_Route is removed, THE SearchIssues_Function SHALL remain exported from jiraApi.js for use by internal callers
2. WHEN the getIssue() function is called, THE SearchIssues_Function SHALL execute the JQL query and return the matching issue
3. WHEN the SearchIssuesByKeys_Function is called, THE SearchIssues_Function SHALL execute the bulk JQL query and return matching issues