cve-dashboard/.kiro/specs/fp-attachment-library/requirements.md

# Requirements Document

## Introduction

The FP Attachment Library feature extends the FP submission workflow (both create and edit flows) to allow users to attach existing documents from the CVE document library stored in the `documents` table, in addition to the current local file upload capability. This eliminates the need to re-download and re-upload files that already exist in the system, streamlining the attachment workflow for FP submissions.

## Glossary

- **Dashboard**: The STEAM Security Dashboard application
- **FP_Create_Modal**: The FpWorkflowModal component used to create new FP workflow submissions (in ReportingPage.js)
- **FP_Edit_Modal**: The FpEditModal component used to edit existing FP workflow submissions (in ReportingPage.js)
- **Document_Library**: The collection of files stored in the `documents` table, organized by CVE ID and vendor, with files on disk under `uploads/{cve_id}/{vendor}/`
- **Attachment_Source_Picker**: The UI component that lets users choose between uploading a local file or selecting an existing document from the Document_Library
- **Document_Search_API**: The backend endpoint that searches and returns documents from the Document_Library for selection
- **Library_Document**: A document record from the `documents` table, containing id, cve_id, vendor, name, type, file_path, file_size, mime_type, uploaded_at, and notes
- **Ivanti_API**: The external Ivanti/RiskSense API that receives FP workflow submissions and file attachments

## Requirements

### Requirement 1: Document Search API

**User Story:** As an editor, I want to search the document library from within the FP workflow, so that I can find and attach existing documents without leaving the modal.

#### Acceptance Criteria

1. WHEN a search query is provided, THE Document_Search_API SHALL return Library_Document records whose name, cve_id, or vendor fields contain the query string
2. WHEN no search query is provided, THE Document_Search_API SHALL return the most recent Library_Document records ordered by uploaded_at descending
3. THE Document_Search_API SHALL limit results to a maximum of 50 records per request
4. THE Document_Search_API SHALL return each Library_Document with its id, cve_id, vendor, name, type, file_size, mime_type, and uploaded_at fields
5. THE Document_Search_API SHALL require an authenticated session before returning results
6. IF the database query fails, THEN THE Document_Search_API SHALL return an error response with a 500 status code

### Requirement 2: Attachment Source Picker in FP Create Modal

**User Story:** As an editor, I want to choose between uploading a local file or selecting a document from the library when creating an FP submission, so that I can attach evidence without re-uploading files that already exist in the system.

#### Acceptance Criteria

1. THE FP_Create_Modal SHALL display the Attachment_Source_Picker with two modes: local file upload and library document selection
2. WHEN the user selects local file upload mode, THE FP_Create_Modal SHALL display the existing drag-and-drop zone and file picker
3. WHEN the user selects library document selection mode, THE FP_Create_Modal SHALL display a search input and a scrollable list of matching Library_Document records
4. WHEN the user types in the library search input, THE FP_Create_Modal SHALL query the Document_Search_API and display matching results within 300 milliseconds of the last keystroke (debounced)
5. WHEN the user selects a Library_Document from the search results, THE FP_Create_Modal SHALL add the document to the attachment list with a visual indicator distinguishing it from locally uploaded files
6. THE FP_Create_Modal SHALL allow the user to remove any attachment from the list, whether it is a local file or a Library_Document
7. THE FP_Create_Modal SHALL allow mixing local file uploads and Library_Document selections in the same submission
8. THE FP_Create_Modal SHALL display the file name, file size, and CVE ID for each selected Library_Document in the attachment list

### Requirement 3: Attachment Source Picker in FP Edit Modal

**User Story:** As an editor, I want to attach existing library documents to an FP submission I am editing, so that I can add supporting evidence after the initial submission without re-uploading files.

#### Acceptance Criteria

1. THE FP_Edit_Modal SHALL replace the static "upload in Ivanti" message on the attachments tab with the Attachment_Source_Picker
2. WHEN the user selects library document selection mode, THE FP_Edit_Modal SHALL display a search input and a scrollable list of matching Library_Document records
3. WHEN the user selects local file upload mode, THE FP_Edit_Modal SHALL display a drag-and-drop zone and file picker for local files
4. THE FP_Edit_Modal SHALL continue to display existing attachments from the initial submission above the Attachment_Source_Picker
5. WHILE the submission lifecycle_status is "approved", THE FP_Edit_Modal SHALL disable the Attachment_Source_Picker and prevent adding new attachments
6. THE FP_Edit_Modal SHALL allow the user to upload or attach selected documents by clicking a submit action button

### Requirement 4: Backend Handling of Library Document Attachments

**User Story:** As an editor, I want library documents to be sent to the Ivanti API the same way as local uploads, so that all attachments appear correctly on the Ivanti workflow.

#### Acceptance Criteria

1. WHEN the FP submission includes Library_Document references, THE Dashboard backend SHALL read the referenced files from disk using the file_path stored in the documents table
2. WHEN the FP submission includes both local files and Library_Document references, THE Dashboard backend SHALL send all attachments to the Ivanti_API in a single multipart request
3. IF a referenced Library_Document file_path does not exist on disk, THEN THE Dashboard backend SHALL return an error identifying the missing file and skip that attachment
4. IF a referenced Library_Document id does not exist in the documents table, THEN THE Dashboard backend SHALL return a 400 error identifying the invalid document ID
5. THE Dashboard backend SHALL validate that each referenced Library_Document id is a positive integer before querying the database
6. THE Dashboard backend SHALL include Library_Document attachments in the attachment_results_json field of the submission record, with a source indicator distinguishing them from local uploads
7. WHEN recording attachment results, THE Dashboard backend SHALL store the original document name from the Library_Document record as the filename

### Requirement 5: Duplicate Attachment Prevention

**User Story:** As an editor, I want the system to prevent me from attaching the same library document twice, so that I do not create redundant attachments on the Ivanti workflow.

#### Acceptance Criteria

1. WHEN the user selects a Library_Document that is already in the attachment list, THE Attachment_Source_Picker SHALL not add a duplicate entry
2. THE Attachment_Source_Picker SHALL visually indicate Library_Document records that are already attached by showing them as disabled or checked in the search results
3. WHEN the user removes a previously selected Library_Document from the attachment list, THE Attachment_Source_Picker SHALL re-enable that document in the search results

### Requirement 6: Attachment List Display

**User Story:** As an editor, I want to clearly distinguish between local uploads and library documents in the attachment list, so that I know the source of each attachment before submitting.

#### Acceptance Criteria

1. THE Attachment_Source_Picker SHALL display a source badge or icon next to each attachment indicating whether it is a "Local Upload" or a "Library Document"
2. THE Attachment_Source_Picker SHALL display the file name and file size for all attachments regardless of source
3. WHEN displaying a Library_Document attachment, THE Attachment_Source_Picker SHALL also display the associated CVE ID and vendor name
4. THE Attachment_Source_Picker SHALL display a remove button for each attachment in the list