@ihasq/files

End-to-end encrypted file explorer for remote servers

---

A modern, secure file explorer designed for VPS and remote server management over SSH. All communications are encrypted using X25519 key exchange and XSalsa20-Poly1305 (NaCl secretbox), providing security beyond TLS.

Features

• End-to-End Encryption - X25519 ECDH key exchange + NaCl secretbox encryption
• Zero Configuration - Single command to start, works out of the box
• Modern UI - Clean interface with dark/light theme (auto-detected from system)
• Monaco Editor - Full-featured code editor for text files with syntax highlighting
• Media Streaming - Video/audio streaming with seek support (Range requests)
• Drag & Drop - Upload files, move/copy with drag, marquee selection
• Undo/Redo - Full undo/redo support for file operations (Ctrl+Z/Y)
• Cross-Platform - Works on Windows, macOS, and Linux
• Gzip Compression - All API responses are compressed

Installation

# Using npx (no installation required)
npx @ihasq/files <port>

# Or install globally
npm install -g @ihasq/files
files <port>

Quick Start

# Start the file explorer on port 8080
npx @ihasq/files 8080

# Then open http://localhost:8080 in your browser

For remote servers, use SSH port forwarding:

# On your local machine
ssh -L 8080:localhost:8080 user@your-server

# On the remote server
npx @ihasq/files 8080

# Access via http://localhost:8080 on your local browser

Usage

Navigation

• Click - Select file/folder
• Double-click - Open folder / Edit file / Play media
• Ctrl+Click - Add to selection
• Shift+Click - Range selection
• Drag - Marquee selection (on empty area)

File Operations

Action	Method
Copy	Right-click → Copy / Ctrl+C
Cut	Right-click → Cut / Ctrl+X
Paste	Right-click → Paste / Ctrl+V
Delete	Right-click → Delete
Rename	Right-click → Rename
Move	Drag file to folder
Copy (drag)	Ctrl + Drag file to folder
Undo	Ctrl+Z
Redo	Ctrl+Y or Ctrl+Shift+Z

Views

• List View - Detailed view with name, size, and modified date
• Grid View - Icon-based view for visual browsing
• Zoom - Adjust icon/text size (50% - 200%)
• Sort - Click column headers to sort (Name, Size, Modified)

Editor

• Auto-save after 2 seconds of inactivity
• Manual save with Ctrl+S
• Syntax highlighting for 50+ languages
• Dark theme optimized for code editing

Media Player

• Streaming playback (no full download required)
• Supports: MP4, WebM, MOV, MKV, MP3, WAV, FLAC, and more
• Seek support via HTTP Range requests

Security

Encryption Model

┌─────────────┐                      ┌─────────────┐
│   Browser   │                      │   Server    │
│             │                      │             │
│  Generate   │    Public Key        │  Generate   │
│  Key Pair   │ ─────────────────►   │  Key Pair   │
│             │                      │             │
│             │   ◄─────────────────  │             │
│             │    Public Key        │             │
│             │                      │             │
│  Compute    │                      │  Compute    │
│  Shared Key │                      │  Shared Key │
│             │                      │             │
│  Encrypt    │   Encrypted Data     │  Decrypt    │
│  Request    │ ─────────────────►   │  Request    │
│             │                      │             │
│  Decrypt    │   ◄─────────────────  │  Encrypt   │
│  Response   │   Encrypted Data     │  Response   │
└─────────────┘                      └─────────────┘

• Key Exchange: X25519 (Curve25519 ECDH)
• Symmetric Encryption: XSalsa20-Poly1305 (NaCl secretbox)
• Implementation: TweetNaCl.js

Why Not Just TLS?

While TLS provides transport security, this project adds application-layer encryption:

1. Defense in Depth - Even if TLS is compromised, data remains encrypted
2. No Certificate Management - Works without SSL certificates
3. Auditability - Simple, auditable crypto implementation
4. SSH Tunnel Compatible - Designed for use over SSH port forwarding

Session Management

• Sessions expire after 30 minutes of inactivity
• Stream tokens expire after 1 hour
• No persistent storage of keys

API

All API endpoints (except /api/handshake) require encrypted payloads.

Endpoint	Description
POST /api/handshake	Key exchange
POST /api/list	List directory contents
POST /api/read	Read file content (text)
POST /api/write	Write file content
POST /api/delete	Delete files/folders
POST /api/copy	Copy files/folders
POST /api/move	Move files/folders
POST /api/mkdir	Create directory
POST /api/rename	Rename file/folder
POST /api/properties	Get file properties
POST /api/upload	Upload file
POST /api/download	Download file
POST /api/stream-token	Get streaming token
GET /stream/:token	Stream media file

Configuration

Currently, configuration is done via command-line arguments:

npx @ihasq/files <port>

Argument	Description	Required
port	Server port (1-65535)	Yes

Browser Support

• Chrome/Chromium 80+
• Firefox 75+
• Safari 13.1+
• Edge 80+

Tech Stack

• Frontend: React 19, TypeScript, Vite, Tailwind CSS v4
• UI Components: Radix UI, Lucide Icons
• Editor: Monaco Editor
• Encryption: TweetNaCl
• Backend: Node.js (native HTTP, no Express)

Development

# Clone the repository
git clone https://github.com/ihasq/files.git
cd files

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

License

ISC - Copyright (c) ihasq

Acknowledgments

• TweetNaCl.js - Cryptography library
• Monaco Editor - Code editor
• Radix UI - UI primitives
• Lucide - Icons