Skip to content

README.md

Latest commit

 

History

History
461 lines (347 loc) · 13.4 KB

README.md

File metadata and controls

461 lines (347 loc) · 13.4 KB

🔐 Ghost Drive Frontend

A secure end-to-end encrypted file storage frontend built with React, TypeScript, and Vite. Ghost Drive Frontend provides a modern, user-friendly interface for the Ghost Drive secure file storage system, ensuring that only users can decrypt their files - even the development team cannot access user data.

🚀 Features

  • True End-to-End Encryption: Files are encrypted on the client side using AES-256
  • Client-Side Key Generation: AES keys generated on frontend, preventing backend backdoors
  • PIN-Based Security: User-defined PINs protect encryption keys (PIN never leaves client)
  • Zero-Knowledge Architecture: Server cannot decrypt user files even if compromised
  • Modern React Interface: Built with React 19, TypeScript, and Tailwind CSS
  • Responsive Design: Works seamlessly on desktop and mobile devices
  • File Management: Upload, download, organize, and manage encrypted files
  • Virtual Folder Organization: Create and manage virtual folders for file organization
  • Real-time Updates: Instant feedback for file operations
  • Secure Authentication: JWT-based authentication with secure token management

🛠️ Technology Stack

  • Framework: React 19 - Modern React with concurrent features
  • Language: TypeScript - Type-safe JavaScript
  • Build Tool: Vite - Fast build tool and dev server
  • Styling: Tailwind CSS - Utility-first CSS framework
  • HTTP Client: Axios - Promise-based HTTP client
  • Cryptography: Web Crypto API - Native browser cryptography
  • Package Manager: Bun - Fast JavaScript runtime and package manager

📁 Project Structure

ghost-drive-fe/
├── public/                 # Static assets
├── src/
│   ├── components/         # Reusable React components
│   │   └── PinModal.tsx    # PIN input modal component
│   ├── pages/              # Page components
│   │   ├── LoginPage.tsx   # User login page
│   │   └── RegisterPage.tsx # User registration page
│   ├── utils/              # Utility functions
│   │   ├── crypto.ts       # Cryptography utilities
│   │   └── README.md       # Crypto module documentation
│   ├── App.tsx             # Main application component
│   ├── main.tsx            # Application entry point
│   └── index.css           # Global styles
├── package.json            # Dependencies and scripts
├── vite.config.ts          # Vite configuration
├── tsconfig.json           # TypeScript configuration
└── README.md               # Project documentation

🔒 How Encryption Works

Ghost Drive Frontend implements a sophisticated encryption system that ensures complete privacy:

Encryption Architecture

  1. PIN-Based Key Derivation: Users provide a secret 6-digit PIN
  2. Client-Side AES Key Generation: Frontend generates a random AES-256 key for file encryption
  3. Key Encryption: The AES key is encrypted using the user's PIN on the client side
  4. Secure Storage: Only the encrypted AES key is sent to and stored in the database
  5. Zero-Knowledge: Backend never sees the plain PIN or plain AES key
  6. Client-Side Processing: All file encryption/decryption happens on the client

Step-by-Step Process

File Upload (Encryption)

┌─────────────┐
│    User     │
│  Selects    │
│    File     │
└─────────────┘
        │
        ▼
┌─────────────┐
│ Generate    │
│ Random AES  │
│ Key         │
└─────────────┘
        │
        ▼
┌─────────────┐
│ Encrypt     │
│ File with   │
│ AES Key     │
└─────────────┘
        │
        ▼
┌─────────────┐    Encrypted    ┌─────────────┐
│    User     │ ───────────────►│   Backend   │
│             │      File       │             │
└─────────────┘                 └─────────────┘
                                    │
                                    ▼
┌─────────────┐    Encrypted    ┌─────────────┐
│   MinIO     │ ◄────────────── │   Backend   │
│  Storage    │      File       │             │
└─────────────┘                 └─────────────┘

File Download (Decryption)

┌─────────────┐    Request     ┌─────────────┐
│    User     │ ──────────────►│   Backend   │
│             │   File ID      │             │
└─────────────┘                └─────────────┘
                                    │
                                    ▼
┌─────────────┐    Encrypted    ┌─────────────┐
│    User     │ ◄────────────── │   MinIO     │
│             │      File       │  Storage    │
└─────────────┘                 └─────────────┘
        │
        ▼
┌─────────────┐
│ Decrypt     │
│ File with   │
│ AES Key     │
└─────────────┘
        │
        ▼
┌─────────────┐
│ Original    │
│ File        │
│ Restored    │
└─────────────┘

📋 Prerequisites

  • Node.js (v18 or higher) or Bun (v1.0.0 or higher)
  • Modern web browser with Web Crypto API support
  • Ghost Drive Backend server running (see backend documentation)

🚀 Quick Start

1. Clone the Repository

git clone <repository-url>
cd ghost-drive-fe

2. Install Dependencies

Using Bun (recommended):

bun install

Using npm:

npm install

Using yarn:

yarn install

3. Environment Configuration

Create a .env file in the root directory:

# Backend API Configuration
VITE_API_BASE_URL=http://localhost:3000
VITE_API_TIMEOUT=30000

# Application Configuration
VITE_APP_NAME=Ghost Drive
VITE_APP_VERSION=1.0.0

# Feature Flags
VITE_ENABLE_DEBUG_MODE=false
VITE_ENABLE_ANALYTICS=false

4. Start Development Server

Using Bun:

bun dev

Using npm:

npm run dev

Using yarn:

yarn dev

The application will be available at: http://localhost:5173

5. Build for Production

Using Bun:

bun run build

Using npm:

npm run build

Using yarn:

yarn build

🔧 Development

Available Scripts

# Development with hot reload
bun dev

# Build for production
bun run build

# Preview production build
bun run preview

# Run linting
bun run lint

Adding New Features

  1. Create Components: Add new components in src/components/
  2. Create Pages: Add new pages in src/pages/
  3. Add Utilities: Add utility functions in src/utils/
  4. Update Styles: Modify Tailwind classes or add custom CSS
  5. Test Features: Test in development mode before deployment

Code Structure Guidelines

  • Components: Use functional components with hooks
  • TypeScript: Use strict TypeScript for type safety
  • Styling: Use Tailwind CSS utility classes
  • State Management: Use React hooks for local state
  • API Calls: Use Axios for HTTP requests
  • Error Handling: Implement proper error boundaries and error handling

🔐 Security Considerations

Frontend Security

  • PIN Security: Users should use strong, unique 6-digit PINs
  • Client-Side Key Generation: AES keys are generated on the frontend
  • PIN Never Transmitted: User PINs never leave the client
  • Zero-Knowledge Architecture: Backend cannot decrypt files
  • HTTPS Required: Always use HTTPS in production
  • Secure Storage: Use secure storage for sensitive data
  • Input Validation: Validate all user inputs
  • XSS Prevention: Sanitize user inputs and outputs

Browser Compatibility

  • Web Crypto API: Requires modern browsers with Web Crypto API support
  • HTTPS Requirement: Web Crypto API only works in secure contexts
  • Fallback Support: Consider fallback mechanisms for older browsers

Development Security

  • Environment Variables: Never commit sensitive data to version control
  • API Keys: Store API keys in environment variables
  • Debug Mode: Disable debug mode in production
  • Error Messages: Don't expose sensitive information in error messages

📱 User Interface Features

Authentication

  • User Registration: Secure user registration with PIN setup
  • User Login: JWT-based authentication with PIN verification
  • PIN Management: Secure PIN change functionality
  • Session Management: Automatic token refresh and session handling

File Management

  • File Upload: Drag-and-drop file upload with encryption
  • File Download: Secure file download with automatic decryption
  • File Organization: Virtual folder creation and management
  • File Preview: Preview supported file types
  • File Search: Search files by name and content
  • File Sharing: Secure file sharing capabilities

User Experience

  • Responsive Design: Works on desktop, tablet, and mobile
  • Dark/Light Mode: User preference-based theme switching
  • Progress Indicators: Real-time upload/download progress
  • Error Handling: User-friendly error messages and recovery
  • Loading States: Smooth loading animations and states

🔄 API Integration

Authentication Endpoints

// User registration
POST /api/users/register
{
  "username": "[email protected]",
  "password": "securepassword",
  "aesKeyEncrypted": "encrypted-aes-key-string"
}

// User login
POST /api/users/login
{
  "username": "[email protected]",
  "password": "securepassword"
}

File Management Endpoints

// Get upload presigned URL
GET /api/files/upload-url?filename=document.pdf&path=/Documents/

// Get download presigned URL
GET /api/files/download-url/:fileId

// List user files
GET /api/files?path=/Documents/

// Delete file
DELETE /api/files/:fileId

User Management Endpoints

// Get user profile
GET /api/users/me

// Update encrypted AES key
POST /api/users/update-aes-key-encrypted
{
  "aesKeyEncrypted": "new-encrypted-aes-key-string"
}

// Update user avatar
POST /api/users/update-avatar
{
  "avatar": "base64-encoded-avatar-image"
}

🧪 Testing

Manual Testing

  1. User Registration: Test user registration with PIN setup
  2. User Login: Test login with correct and incorrect credentials
  3. File Upload: Test file upload with encryption
  4. File Download: Test file download with decryption
  5. PIN Change: Test PIN change functionality
  6. Error Handling: Test various error scenarios

Automated Testing

# Run unit tests
bun test

# Run integration tests
bun test:integration

# Run end-to-end tests
bun test:e2e

🚀 Deployment

Production Build

# Build for production
bun run build

# Preview production build
bun run preview

Deployment Options

  1. Static Hosting: Deploy to Vercel, Netlify, or similar
  2. CDN: Use CDN for global distribution
  3. Docker: Containerize the application
  4. Cloud Platforms: Deploy to AWS, Google Cloud, or Azure

Environment Configuration

# Production environment variables
VITE_API_BASE_URL=https://api.ghostdrive.com
VITE_APP_NAME=Ghost Drive
VITE_ENABLE_DEBUG_MODE=false
VITE_ENABLE_ANALYTICS=true

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow TypeScript best practices
  • Use meaningful commit messages
  • Add tests for new features
  • Update documentation as needed
  • Follow the existing code style

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Built with modern web technologies for maximum security and performance
  • Special thanks to the React, TypeScript, and Vite communities
  • Inspired by the need for truly secure file storage solutions

📞 Support

  • Documentation: Check the docs folder for detailed guides
  • Issues: Report bugs and request features on GitHub
  • Discussions: Join community discussions on GitHub
  • Security: Report security vulnerabilities privately

⚠️ Important: This is a security-critical application. Always review the encryption implementation and conduct security audits before deploying to production.

🔐 Remember: The strength of your encryption depends on the strength of your PIN. Choose wisely!

🌐 Browser Support: This application requires modern browsers with Web Crypto API support and HTTPS.