zephyrfs-web Public

Watch 0 Fork 0 Star 0
markdown · 3601 bytes Raw Blame History

ZephyrFS Web Interface

A modern web interface and WebDAV server for ZephyrFS distributed storage system.

Features

  • RESTful API - Complete file management operations
  • JWT Authentication - Secure token-based authentication
  • WebDAV Server - Native OS integration for mounting as network drive
  • Real-time Updates - WebSocket-based status monitoring
  • Zero-Knowledge Security - Preserves ZephyrFS encryption architecture
  • High Performance - Sub-2-second response times with streaming support

Quick Start

Development

  1. Install dependencies

    cd server
npm install

  2. Configure environment

    cp .env.example .env
# Edit .env with your settings

  3. Start development server

    npm run dev

Production

  1. Build the application

    npm run build

  2. Start production server

    npm start

Docker

docker-compose up -d

API Endpoints

Authentication

  • POST /api/auth/login - Login with username/password
  • POST /api/auth/refresh - Refresh access token
  • POST /api/auth/logout - Logout and invalidate session
  • GET /api/auth/me - Get current user info

Files

  • GET /api/files - List files in directory
  • POST /api/files/upload - Upload file
  • GET /api/files/:id/download - Download file
  • GET /api/files/:id/info - Get file metadata
  • DELETE /api/files/:id - Delete file

Status

  • GET /api/health - Health check
  • GET /api/status/network - Network status
  • GET /api/status/node - Node status
  • GET /api/status/ws - WebSocket status updates

WebDAV

  • GET /api/webdav - WebDAV discovery info
  • ALL /api/webdav/* - WebDAV protocol endpoints

WebDAV Setup

The WebDAV server allows mounting ZephyrFS as a network drive:

Windows

  1. Open File Explorer
  2. Right-click "This PC" → "Map network drive"
  3. Click "Connect to a Web site"
  4. Enter: http://localhost:3000/api/webdav/
  5. Username: zephyrfs, Password: webdav

macOS

  1. Open Finder
  2. Go → Connect to Server (⌘K)
  3. Enter: http://localhost:3000/api/webdav/
  4. Username: zephyrfs, Password: webdav

Linux

  1. Open file manager
  2. Other Locations → Connect to Server
  3. Enter: http://localhost:3000/api/webdav/
  4. Username: zephyrfs, Password: webdav

Configuration

Environment variables (see .env.example):

  • PORT - Server port (default: 3000)
  • ZEPHYRFS_NODE_URL - ZephyrFS node URL
  • JWT_SECRET - JWT signing secret (min 32 chars)
  • CORS_ORIGINS - Allowed CORS origins
  • WEBDAV_ENABLED - Enable WebDAV server
  • LOG_LEVEL - Logging level (debug, info, warn, error)

Testing

npm test

Architecture

The web interface acts as a bridge between web clients and the ZephyrFS node:

Web Client/WebDAV → Fastify API → ZephyrFS Client → ZephyrFS Node
  • Fastify - High-performance web framework
  • JWT Authentication - Stateless authentication
  • WebDAV Server - Standards-compliant DAV implementation
  • ZephyrFS Client - HTTP client for node communication
  • Zero-Knowledge - Encryption keys never leave client side

Security

  • JWT tokens with configurable expiration
  • Rate limiting (100 requests/minute per IP)
  • Security headers (HSTS, CSP, etc.)
  • CORS protection
  • Input validation with Zod schemas
  • Secure error handling (no info leakage)

Performance

  • Sub-200ms API response times
  • Streaming file uploads/downloads
  • Efficient chunked transfer
  • WebSocket real-time updates
  • Connection pooling and timeouts
View source
1 # ZephyrFS Web Interface
2
3 A modern web interface and WebDAV server for ZephyrFS distributed storage system.
4
5 ## Features
6
7 - **RESTful API** - Complete file management operations
8 - **JWT Authentication** - Secure token-based authentication
9 - **WebDAV Server** - Native OS integration for mounting as network drive
10 - **Real-time Updates** - WebSocket-based status monitoring
11 - **Zero-Knowledge Security** - Preserves ZephyrFS encryption architecture
12 - **High Performance** - Sub-2-second response times with streaming support
13
14 ## Quick Start
15
16 ### Development
17
18 1. **Install dependencies**
19 ```bash
20 cd server
21 npm install
22 ```
23
24 2. **Configure environment**
25 ```bash
26 cp .env.example .env
27 # Edit .env with your settings
28 ```
29
30 3. **Start development server**
31 ```bash
32 npm run dev
33 ```
34
35 ### Production
36
37 1. **Build the application**
38 ```bash
39 npm run build
40 ```
41
42 2. **Start production server**
43 ```bash
44 npm start
45 ```
46
47 ### Docker
48
49 ```bash
50 docker-compose up -d
51 ```
52
53 ## API Endpoints
54
55 ### Authentication
56 - `POST /api/auth/login` - Login with username/password
57 - `POST /api/auth/refresh` - Refresh access token
58 - `POST /api/auth/logout` - Logout and invalidate session
59 - `GET /api/auth/me` - Get current user info
60
61 ### Files
62 - `GET /api/files` - List files in directory
63 - `POST /api/files/upload` - Upload file
64 - `GET /api/files/:id/download` - Download file
65 - `GET /api/files/:id/info` - Get file metadata
66 - `DELETE /api/files/:id` - Delete file
67
68 ### Status
69 - `GET /api/health` - Health check
70 - `GET /api/status/network` - Network status
71 - `GET /api/status/node` - Node status
72 - `GET /api/status/ws` - WebSocket status updates
73
74 ### WebDAV
75 - `GET /api/webdav` - WebDAV discovery info
76 - `ALL /api/webdav/*` - WebDAV protocol endpoints
77
78 ## WebDAV Setup
79
80 The WebDAV server allows mounting ZephyrFS as a network drive:
81
82 ### Windows
83 1. Open File Explorer
84 2. Right-click "This PC" → "Map network drive"
85 3. Click "Connect to a Web site"
86 4. Enter: `http://localhost:3000/api/webdav/`
87 5. Username: `zephyrfs`, Password: `webdav`
88
89 ### macOS
90 1. Open Finder
91 2. Go → Connect to Server (⌘K)
92 3. Enter: `http://localhost:3000/api/webdav/`
93 4. Username: `zephyrfs`, Password: `webdav`
94
95 ### Linux
96 1. Open file manager
97 2. Other Locations → Connect to Server
98 3. Enter: `http://localhost:3000/api/webdav/`
99 4. Username: `zephyrfs`, Password: `webdav`
100
101 ## Configuration
102
103 Environment variables (see `.env.example`):
104
105 - `PORT` - Server port (default: 3000)
106 - `ZEPHYRFS_NODE_URL` - ZephyrFS node URL
107 - `JWT_SECRET` - JWT signing secret (min 32 chars)
108 - `CORS_ORIGINS` - Allowed CORS origins
109 - `WEBDAV_ENABLED` - Enable WebDAV server
110 - `LOG_LEVEL` - Logging level (debug, info, warn, error)
111
112 ## Testing
113
114 ```bash
115 npm test
116 ```
117
118 ## Architecture
119
120 The web interface acts as a bridge between web clients and the ZephyrFS node:
121
122 ```
123 Web Client/WebDAV → Fastify API → ZephyrFS Client → ZephyrFS Node
124 ```
125
126 - **Fastify** - High-performance web framework
127 - **JWT Authentication** - Stateless authentication
128 - **WebDAV Server** - Standards-compliant DAV implementation
129 - **ZephyrFS Client** - HTTP client for node communication
130 - **Zero-Knowledge** - Encryption keys never leave client side
131
132 ## Security
133
134 - JWT tokens with configurable expiration
135 - Rate limiting (100 requests/minute per IP)
136 - Security headers (HSTS, CSP, etc.)
137 - CORS protection
138 - Input validation with Zod schemas
139 - Secure error handling (no info leakage)
140
141 ## Performance
142
143 - Sub-200ms API response times
144 - Streaming file uploads/downloads
145 - Efficient chunked transfer
146 - WebSocket real-time updates
147 - Connection pooling and timeouts