Peek Explorer

A secure, modern static file explorer and manager for Node.js with a redesigned web UI, full-featured CLI, and comprehensive file management system.

Quick Start

Installation

npm install peek-explorer

Usage

# Start server
peek start

# Start with custom directory
peek start --dir /path/to/files

# Start with token authentication
peek token generate
peek start --token <your-token>

# Interactive mode
peek cli

# Help
peek --help

Then open http://127.0.0.1:3000 in your browser.

---

Features

Security

• 8 Critical Vulnerabilities Fixed
  • Path traversal prevention
  • Token-based authentication
  • CSRF protection on all mutations
  • Rate limiting (300 req/min per IP)
  • Binary-safe file uploads
  • Request body size limits
  • Security headers (CSP, X-Frame-Options)
  • XSS and injection prevention

File Management

• Trash System - Move files to trash instead of permanent deletion
• File Recovery - Restore deleted files from trash with metadata
• Auto-Backups - Automatic backups before editing
• Batch Operations - Copy, move, delete multiple files at once
• Advanced Search - Find files by name, content, size, or modification time
• Duplicate Detection - Identify potential duplicate files
• File Checksums - SHA256 hashes for integrity verification

Modern UI

• Dark & Light Theme - Toggle between themes (persisted)
• Responsive Design - Works on desktop, tablet, mobile
• Grid & List Views - Switch between view modes
• Breadcrumb Navigation - Easy navigation through directories
• Inline Editor - Edit text files directly in the browser
• File Preview - Preview images and documents in modal
• Drag & Drop - Upload files by dragging and dropping
• Real-time Search - Filter and search files instantly

CLI Features

• Interactive Mode - Full CLI with start/stop/restart commands
• Token Generation - Generate secure auth tokens
• Configuration - Support for config files and environment variables
• Status Monitoring - Check server status and configuration
• Directory Management - Change directories on the fly

File Analysis

• Directory Statistics - Count files, folders, calculate sizes
• File Type Detection - Categorize files (image, video, document, code, etc.)
• Size Reports - Generate detailed size reports
• Modification Tracking - Track recently modified files

File Monitoring

• Real-time Watcher - Monitor file system changes
• Change Logging - Log all file operations with timestamps
• Event Filtering - Query changes by type, name, or time range
• Sync Tracking - Track pending changes for sync operations

---

Installation & Setup

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0

Install from npm

npm install peek-explorer

Install globally

npm install -g peek-explorer
peek start

Local development

git clone https://github.com/aydope/peek.git
cd peek
npm install
npm run dev

---

Usage Examples

Basic Server

peek start
# → http://127.0.0.1:3000

With Authentication

peek token generate
# Output: Your token: a1b2c3d4e5f6...

peek start --token a1b2c3d4e5f6...

Read-only Mode

peek start --readonly
# Users can view but cannot upload, edit, or delete

Custom Directory

peek start --dir /home/user/documents

Custom Port

peek start --port 8080
# → http://127.0.0.1:8080

Auto-open Browser

peek start --open
# Browser opens automatically

Interactive CLI

peek cli

# Available commands:
# start         - Start the server
# stop          - Stop the server
# restart       - Restart the server
# status        - Show server status
# port <num>    - Change port
# dir <path>    - Change directory
# token         - Show/generate tokens
# readonly      - Toggle read-only mode
# copy          - Copy current URL
# help          - Show help
# clear         - Clear screen
# exit          - Exit CLI

---

Configuration

Config File

Create peek.config.json:

{
  "port": 3000,
  "host": "127.0.0.1",
  "directory": "./public",
  "token": "your-secret-token",
  "readonly": false,
  "maxFileSize": 52428800,
  "maxUploadBytes": 104857600,
  "rateLimit": {
    "windowMs": 60000,
    "maxRequests": 300
  }
}

Environment Variables

PEEK_PORT=3000
PEEK_HOST=127.0.0.1
PEEK_DIR=./public
PEEK_TOKEN=your-secret-token
PEEK_READONLY=false

.peekignore

Create .peekignore to hide files:

node_modules
.git
.env
*.log
.DS_Store

---

API Endpoints

GET /~/{path} - Browse Directory

curl http://127.0.0.1:3000/~/
curl "http://127.0.0.1:3000/~/?sortBy=modified&sortDir=desc"

GET /f/{path} - Get File

curl http://127.0.0.1:3000/f/document.pdf
curl http://127.0.0.1:3000/f/image.jpg?download=1

POST /api/files - Create File

curl -X POST http://127.0.0.1:3000/api/files \
  -H "Content-Type: application/json" \
  -d '{"path":"newfile.txt","content":"Hello"}'

POST /api/upload - Upload File

curl -X POST http://127.0.0.1:3000/api/upload \
  -F "file=@document.pdf" \
  -F "path=/documents/"

PUT /api/rename - Rename File

curl -X PUT http://127.0.0.1:3000/api/rename \
  -H "Content-Type: application/json" \
  -d '{"oldPath":"old.txt","newPath":"new.txt"}'

DELETE /api/delete - Delete File

curl -X DELETE http://127.0.0.1:3000/api/delete \
  -H "Content-Type: application/json" \
  -d '{"path":"file.txt"}'

---

Architecture

Modular Structure

peek/
├── bin/peek.js              - CLI entry point
├── src/
│   ├── security.js          - Auth, validation, rate limiting
│   ├── server.js            - HTTP server core
│   ├── fileSystem.js        - File operations
│   ├── config.js            - Configuration
│   ├── logger.js            - Logging
│   ├── cli.js               - Interactive CLI
│   ├── features.js          - File analysis
│   ├── recovery.js          - Trash system
│   ├── search.js            - Search features
│   ├── batch.js             - Batch operations
│   ├── watcher.js           - File monitoring
│   ├── routes/
│   │   ├── api.js           - JSON API endpoints
│   │   └── pages.js         - HTML pages
│   └── ui/
│       ├── client.js        - Browser JavaScript
│       ├── layout.js        - HTML builder
│       └── styles.js        - CSS styles
├── package.json
├── README.md
└── .peekignore

---

Security

Fixed Vulnerabilities

1. Path Traversal - Normalized path validation with separator checks
2. Missing Authentication - Token-based auth with timing-safe comparison
3. Symlink Bypass - Realpath validation with recursive checks
4. Binary Corruption - Multipart upload with binary-safe handling
5. No Size Limits - Request body and file size limits enforced
6. No CSRF - Origin header validation on state-changing requests
7. No Rate Limiting - Fixed-window rate limiter (300 req/min)
8. XSS Prevention - Content-Security-Policy headers active

Best Practices

• Fail-closed validation
• Timing-safe token comparison
• Security headers (CSP, X-Frame-Options, Referrer-Policy)
• HTTPS ready (with Referrer-Policy: no-referrer)
• CORS-ready (Origin validation)

---

Performance

• Lightweight - ~50KB on disk (without node_modules)
• Fast - Responds in <100ms for typical operations
• Scalable - Rate limiting prevents abuse
• Memory Efficient - Streaming file upload/download

---

Contributing

Contributions are welcome! Please:

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

---

License

MIT License - see LICENSE file for details

---

Support

• Documentation
• Report Bug
• Request Feature

---

Changelog

See CHANGES.md for detailed changelog and security fixes.

---

Credits

Built with ❤️ by Aydope

---

Links

• GitHub
• npm Package
• Issues
• Discussions