## AI Master Prompt: SafeDownload Shield - Secure File Downloader
### 1. PROJECT OVERVIEW:
**Application Name:** SafeDownload Shield
**Purpose:** To provide a secure and trustworthy method for users to download and manage potentially flagged software and tools, such as `yt-dlp`, that are often warned by browsers or antivirus software as 'suspicious downloads'.
**Problem Solved:** Many users encounter warnings from their browsers (like Chrome) or security software when attempting to download legitimate and useful tools. This creates friction, uncertainty, and discourages the use of valuable software. SafeDownload Shield aims to eliminate this by offering a verified download pathway, source verification, and a secure sandbox-like environment for managing these files.
**Value Proposition:** Download essential tools with confidence. SafeDownload Shield acts as a digital gatekeeper, ensuring the integrity and safety of your downloads, bypassing browser warnings with verified security.
**Target Audience:** Tech-savvy individuals, software developers, system administrators, media downloaders, and general internet users concerned about download security. Especially users who regularly utilize tools like `yt-dlp` but hesitate due to browser warnings.
**Theme:** B2C Software Security / Utility Tool
**Monetization Model:** Freemium (Basic features free, advanced features via subscription).
### 2. TECH STACK:
* **Frontend Framework:** React (using Vite for fast development server and build)
* **UI Library/Framework:** Tailwind CSS (for utility-first styling) and Headless UI (for accessible, unstyled components)
* **State Management:** Zustand (for lightweight and efficient global state management)
* **Routing:** React Router DOM (for managing different views/pages within the SPA)
* **HTTP Client:** Axios (for making API requests)
* **Electron (for Desktop App):** To package the React SPA into a cross-platform desktop application (Windows, macOS, Linux).
* **File System Operations:** Node.js `fs` module and potentially libraries for hashing and signature verification (e.g., `crypto` module).
* **Download Management:** Libraries like `download` or custom Node.js streams.
* **Sandbox/Security:** Potentially leveraging OS-level security features or dedicated libraries for isolated execution environments if necessary for advanced features, though MVP will focus on verification and secure storage.
### 3. CORE FEATURES & USER FLOWS:
**A. Verified Download Hub:**
* **User Flow:**
1. User opens the application.
2. Navigates to the 'Download Hub' section.
3. Enters the name of the tool they wish to download (e.g., `yt-dlp`).
4. Clicks 'Search' or 'Find Secure Download'.
5. The application queries its curated, verified sources list.
6. If a verified source is found, the application displays the tool name, version, a brief description, and the verified download button.
7. If no verified source is found, a message indicates this, perhaps offering to add it to a watchlist for future verification.
8. User clicks the 'Download' button.
9. The application initiates the download process securely.
* **Details:** This feature relies on a pre-vetted list of official repositories and download mirrors for popular developer tools. It acts as a curated index rather than a direct file host.
**B. Secure Download Manager:**
* **User Flow:**
1. Once a download is initiated from the Hub, the file is downloaded directly by the application, not the browser.
2. The download progress is displayed within the application's UI (e.g., a progress bar).
3. Upon completion, the file is saved to a designated secure directory managed by SafeDownload Shield (e.g., `~/Documents/SafeDownloadShield/Downloads/`).
4. The application immediately proceeds to the 'File Verification' step.
* **Details:** This bypasses the browser's download handling and associated security scans/warnings. The download happens within the application's process.
**C. File Integrity Verification:**
* **User Flow:**
1. Immediately after a file is downloaded, SafeDownload Shield calculates its cryptographic hash (e.g., SHA-256).
2. It compares this calculated hash against a known, trusted hash value stored in its verified sources database for that specific tool and version.
3. (Optional advanced feature for MVP+): If available, it checks the file's digital signature.
4. The verification status (Verified, Warning, Failed) is clearly displayed next to the downloaded file in the 'Downloads List'.
* **Details:** This is crucial for ensuring the downloaded file hasn't been tampered with or replaced by malicious content. Requires a robust and up-to-date database of hashes and potentially signatures.
**D. Downloaded Files List & Quarantine:**
* **User Flow:**
1. A dedicated 'My Downloads' screen lists all files downloaded via the application.
2. Each list item shows: Tool Name, Version, Download Date, Verification Status (icon/badge).
3. Users can click on a file to see more details (e.g., full hash, source URL, verification report).
4. If a file fails verification or is flagged with a warning, the user has the option to 'Move to Quarantine' or 'Delete'.
5. The 'Quarantine' area isolates suspicious files, preventing accidental execution.
6. Users can review quarantined files and decide to delete them permanently or attempt to restore them (with strong warnings).
* **Details:** Provides a central, organized place to manage downloaded tools and immediate feedback on their security status.
### 4. UI/UX DESIGN:
* **Layout:** Single Page Application (SPA) structure. Main navigation sidebar (or top bar for simplicity) with links to 'Download Hub', 'My Downloads', 'Quarantine', and 'Settings'. The main content area displays the selected section.
* **Color Palette:**
* Primary: Dark slate gray (`#2d3748`) for background/containers.
* Secondary: Deep blue (`#1e3a8a`) for primary actions/hover states.
* Accent: Emerald green (`#047857`) for success/verified states, Amber (`#d97706`) for warnings, Red (`#dc2626`) for errors/failed states.
* Text: Light gray (`#cbd5e0`) for primary text, White (`#ffffff`) for headings.
* **Typography:** Inter or similar sans-serif font. Clear hierarchy with distinct sizes for headings, subheadings, body text, and labels.
* **Component Styling:** Clean, modern, slightly minimalist aesthetic using Tailwind CSS. Focus on clarity and usability. Use subtle animations for transitions and feedback.
* **Responsive Design:** While primarily a desktop application (via Electron), the underlying React app should be responsive. Ensure elements reflow and resize gracefully for different window dimensions. Mobile responsiveness is less critical for the initial desktop release but good practice for potential future web versions.
* **Key Components:** Navigation Menu, Search Bar, File Card (for download hub results), Progress Bar, File List Item (for downloads/quarantine), Status Badges (Verified, Warning, Failed), Modal Dialogs (for confirmations, details).
### 5. COMPONENT BREAKDOWN:
* **`App.jsx`:** Main application component. Sets up routing, global layout, and state providers.
* **`Navigation.jsx`:** Sidebar/top navigation component. Displays links and handles active state.
* **`DownloadHub.jsx`:** Main component for the download section. Contains the search bar and displays search results.
* **`SearchBar.jsx`:** Input field and search button.
* **`ToolResultCard.jsx`:** Displays information about a found tool (name, version, description). Includes the 'Download' button. Receives tool data as props.
* **`Downloader.jsx`:** Manages the download process. Handles API calls for initiating downloads, displays progress.
* **`ProgressBar.jsx`:** Visual representation of download progress. Receives `progress` value as prop.
* **`DownloadsList.jsx`:** Displays the list of downloaded files.
* **`DownloadListItem.jsx`:** Represents a single file in the list. Shows name, status, date. Includes buttons for details, quarantine, delete. Receives file data and functions (e.g., `moveToQuarantine`) as props.
* **`Quarantine.jsx`:** Displays files in the quarantine area.
* **`QuarantineItem.jsx`:** Represents a quarantined file. Shows name, date. Includes buttons for view details, delete, restore. Receives file data and functions as props.
* **`FileDetailsModal.jsx`:** Modal dialog to show detailed information about a downloaded or quarantined file (hashes, source, logs).
* **`Settings.jsx`:** Component for application settings (e.g., download directory, update preferences).
* **`StatusBadge.jsx`:** Reusable component to display verification status with appropriate color coding.
*Props Examples:*
* `ToolResultCard`: `tool={{ name: 'yt-dlp', version: '2023.09.20', description: '...', downloadUrl: '...', expectedHash: '...'}}`, `onDownloadClick={(url, hash) => ...}`
* `DownloadListItem`: `file={{ id: '...', name: '...', status: 'Verified', date: '...', filePath: '...'}}`, `onQuarantineClick={(fileId) => ...}`, `onDeleteClick={(fileId) => ...}`
### 6. DATA MODEL (Zustand State Structure):
```javascript
// store.js
import create from 'zustand';
export const useStore = create(set => ({
// Download Hub State
searchQuery: '',
searchResults: [], // Array of { name, version, description, downloadUrl, expectedHash, sourceVerified: boolean }
isLoadingSearch: false,
error: null,
// Downloads State
downloadingFile: null, // { id, name, progress: 0-100 }
downloadedFiles: [], // Array of { id, name, version, filePath, date, status: 'Pending' | 'Downloading' | 'Verified' | 'Warning' | 'Failed', expectedHash, actualHash }
// Quarantine State
quarantinedFiles: [], // Array of { id, name, filePath, date, reason: 'Verification Failed' | 'User Flagged' }
// Settings State
downloadDirectory: '~/Documents/SafeDownloadShield/Downloads/',
// Actions
setSearchQuery: (query) => set({ searchQuery: query }),
// ... other actions for fetching results, adding downloads, updating status, moving to quarantine etc.
addDownloadedFile: (fileData) => set(state => ({
downloadedFiles: [...state.downloadedFiles, { ...fileData, status: 'Pending', date: new Date() }]
})),
updateDownloadProgress: (fileId, progress) => set(state => ({
downloadingFile: { id: fileId, progress: progress },
downloadedFiles: state.downloadedFiles.map(f => f.id === fileId ? { ...f, status: 'Downloading' } : f)
})),
setFileVerificationStatus: (fileId, status, actualHash = null) => set(state => {
const updatedFiles = state.downloadedFiles.map(f =>
f.id === fileId ? { ...f, status: status, actualHash: actualHash } : f
);
return { downloadedFiles: updatedFiles };
}),
moveToQuarantine: (fileId) => set(state => {
const fileToMove = state.downloadedFiles.find(f => f.id === fileId);
if (fileToMove) {
// Remove from downloadedFiles, add to quarantinedFiles
return {
downloadedFiles: state.downloadedFiles.filter(f => f.id !== fileId),
quarantinedFiles: [...state.quarantinedFiles, { ...fileToMove, status: undefined, reason: 'Verification Failed' }] // Adapt properties as needed
};
}
return {};
}),
// ... more actions
}));
// Mock Data Format Example for downloadedFiles:
// {
// id: 'uuid-1234',
// name: 'yt-dlp.exe',
// version: '2023.09.20',
// filePath: '/path/to/downloads/yt-dlp.exe',
// date: '2023-10-27T10:30:00Z',
// status: 'Verified', // 'Pending', 'Downloading', 'Verified', 'Warning', 'Failed'
// expectedHash: 'a1b2c3d4...',
// actualHash: 'a1b2c3d4...' // populated after verification
// }
```
### 7. ANIMATIONS & INTERACTIONS:
* **Page Transitions:** Subtle fade-in/fade-out animations between different sections (Download Hub, My Downloads, etc.) using `react-transition-group` or Framer Motion.
* **Button Hovers:** Slight scale-up or background color change on interactive elements (buttons, links) using Tailwind's `hover:` variants.
* **Loading States:** Use spinners or skeleton loaders (`react-placeholder` or custom Tailwind components) when fetching search results or performing verification.
* **Download Progress:** Smoothly animating progress bar updates.
* **Micro-interactions:** Subtle visual feedback (e.g., a checkmark animation) when a file is successfully verified or moved to quarantine.
* **Hover Effects on List Items:** Slight background highlight on list items in 'My Downloads' and 'Quarantine' when hovered.
### 8. EDGE CASES:
* **No Verified Sources:** If the 'Download Hub' finds no verified sources for a requested tool, display a user-friendly message, perhaps suggesting they check official websites or request addition to the database.
* **Download Interruption:** Handle network errors during download. Allow retrying the download. Update the file status accordingly.
* **Verification Failures:** Clearly indicate failed verifications. Provide details (mismatched hash, invalid signature). Offer the 'Move to Quarantine' option prominently.
* **Empty States:** Display informative messages and potentially illustrative graphics when 'My Downloads' or 'Quarantine' lists are empty.
* **File System Permissions:** Handle potential errors if the application lacks write permissions to the designated download directory. Guide the user on how to grant permissions.
* **Invalid User Input:** Basic validation for search queries (e.g., disallow excessively long or special character-filled inputs).
* **Disk Space:** Although unlikely for small tools, consider a check for sufficient disk space before starting large downloads (future enhancement).
* **Accessibility (a11y):** Ensure all interactive elements are focusable and usable via keyboard navigation. Use ARIA attributes where necessary. Ensure sufficient color contrast.
* **Corrupted Downloads:** Even if the hash matches, the file might be corrupted. The hash check primarily ensures integrity against modification, not necessarily absence of corruption from the source itself if the source was compromised *before* hashing.
### 9. SAMPLE DATA:
**A. Verified Tool Source Data (Internal Database/API response):**
```json
[
{
"id": "yt-dlp-latest",
"name": "yt-dlp",
"description": "A youtube-dl fork with additional features and fixes.",
"latestVersion": "2023.10.04",
"sources": [
{
"version": "2023.10.04",
"os": "windows",
"architecture": "x64",
"downloadUrl": "https://github.com/yt-dlp/yt-dlp/releases/download/2023.10.04/yt-dlp.exe",
"expectedHash": "sha256:f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1",
"signature": null // Placeholder for future signature verification
},
{
"version": "2023.10.04",
"os": "windows",
"architecture": "x86",
"downloadUrl": "https://github.com/yt-dlp/yt-dlp/releases/download/2023.10.04/yt-dlp_x86.exe",
"expectedHash": "sha256:e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c",
"signature": null
}
]
},
{
"id": "ffmpeg-latest",
"name": "ffmpeg",
"description": "A cross-platform solution to record, convert and stream audio and video.",
"latestVersion": "N-112050-g926a3c3448",
"sources": [
// ... similar structure for ffmpeg binaries ...
]
}
]
```
**B. Mock Data for `downloadedFiles` State:**
```javascript
[
{
"id": "uuid-abc1",
"name": "yt-dlp.exe",
"version": "2023.10.04",
"filePath": "/Users/user/Documents/SafeDownloadShield/Downloads/yt-dlp.exe",
"date": "2023-10-27T11:00:00Z",
"status": "Verified",
"expectedHash": "sha256:f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1",
"actualHash": "sha256:f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1b4c6d8e0f2a1"
},
{
"id": "uuid-def2",
"name": "some_tool.zip",
"version": "1.2.0",
"filePath": "/Users/user/Documents/SafeDownloadShield/Downloads/some_tool.zip",
"date": "2023-10-27T11:05:00Z",
"status": "Warning",
"expectedHash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"actualHash": "sha256:2222222222222222222222222222222222222222222222222222222222222222"
}
]
```
**C. Mock Data for `quarantinedFiles` State:**
```javascript
[
{
"id": "uuid-def2", // Same ID as the failed download
"name": "some_tool.zip",
"filePath": "/Users/user/Documents/SafeDownloadShield/Quarantine/some_tool.zip", // Path updated to quarantine dir
"date": "2023-10-27T11:05:00Z",
"reason": "Verification Failed"
}
]
```
### 10. DEPLOYMENT NOTES:
* **Build Process (Electron):** Use `electron-builder` or `electron-forge` to package the React application into distributable formats for Windows (`.exe`, `.msi`), macOS (`.dmg`), and Linux (`.AppImage`, `.deb`).
* **Environment Variables:** Use `.env` files for managing configuration like the path to the internal verified sources database/API endpoint. Example: `VITE_VERIFIED_SOURCES_API=https://api.safedownloadshield.com/sources`.
* **Performance Optimizations:**
* Code splitting with React's `lazy` and `Suspense` for faster initial load.
* Memoization of components (`React.memo`) where appropriate.
* Efficient state management with Zustand, avoiding unnecessary re-renders.
* Optimize file hashing – potentially use Web Workers for intensive hashing tasks to avoid blocking the main thread.
* **Update Mechanism:** Implement an auto-update mechanism within the Electron app using `autoUpdater` (e.g., via GitHub releases or a dedicated update server) to ensure users are always on the latest, most secure version.
* **Security:** Ensure the application itself doesn't introduce new vulnerabilities. Sanitize all inputs and outputs. Be careful with file system operations.
* **Licensing:** Ensure all included libraries and assets comply with their respective licenses.