Site File Manager
Relevant source files
The following files were used as context for generating this wiki page:
The Site File Manager is the core module responsible for handling member-uploaded static files. It provides tools for uploading, organizing, and editing website content within a restricted sandbox environment. The system enforces strict security protocols, including path normalization and file-type allowlists, to ensure that member activities remain within their designated subdomains.
Members interact with the file manager through a web-based dashboard or an HTTP API. The system manages the underlying storage in the ./data/sites/{name}/ directory, tracking usage metrics such as disk space and file counts against user quotas.
Sources: PLAN.md:1-25, src/server.js:284-300, README.md:1-15
File Operations and Security
The system performs validation on every file operation to prevent directory traversal and unauthorized access. The safeRel function normalizes user-supplied paths by replacing backslashes with forward slashes and splitting them into segments. It rejects paths that include .. segments or exceed a nesting depth of six folders.
Sources: src/util.js:41-54, src/server.js:464-475
Path Validation and Resolution
The server resolves all relative paths against the user's root directory. If a path attempts to escape the root or uses a reserved name, the operation fails.
The diagram shows the logic used to validate and resolve member file paths before execution.
Sources: src/server.js:141-145, src/util.js:41-54
File Type Allist
The system only allows specific file extensions to be saved or served. This prevent execution of server-side scripts or unauthorized binaries.
| Category | Allowed Extensions |
|---|---|
| Text/Code | html, htm, css, js, txt, md, json, xml, svg |
| Images | png, jpg, jpeg, gif, webp, ico, bmp |
| Media | mid, midi, mp3, ogg, wav |
| Other | woff, woff2, ttf, pdf |
Sources: src/util.js:37-40
Upload Systems
The project provides three primary methods for adding files to a site: a standard form upload, a drag-and-drop uploader with progress tracking, and a ZIP import utility.
Sources: src/views.js:336-395, README.md:16-25
Single and Batch Uploads
Standard uploads use multer to handle multipart/form-data. The server stores incoming files in a temporary directory (DATA_DIR/tmp) before moving them to the user's permanent directory. This ensures that failed uploads do not leave partial files in the site folder.
Sources: src/server.js:77-80, src/server.js:520-530
ZIP Import
The ZIP import tool allows members to unpack entire site structures at once. The server processes ZIP files by:
- Validating the total unpacked size against the member's quota.
- Filtering out OS-specific metadata like
.DS_Storeor__MACOSX. - Rejecting symbolic links and encrypted entries.
Sources: src/server.js:550-573, PLAN.md:105-110
Image Processing
When the "shrink" option is enabled during upload, the system uses the sharp library to resize images. It caps photos at 1600 pixels on their longest side and removes hidden camera metadata (EXIF/GPS) to save space and protect privacy.
Sources: src/util.js:105-121, src/server.js:540-545
Usage Tracking and Quotas
The system tracks disk usage asynchronously to avoid blocking the main event loop. Each member has a default quota (typically 500 MB) and a limit of 2,000 files.
Sources: src/server.js:24-35, src/server.js:460-462
Disk Usage Monitoring
A background refreshUsage job periodically re-walks site directories to ensure cached totals match the actual disk state. This catches changes made outside the application, such as manual backups or restores.
The diagram illustrates the asynchronous background process for calculating disk usage.
Sources: src/server.js:127-140, src/util.js:56-78
HTTP API for File Management
The HTTP API allows external programs to manage site files using an API key. Requests must include the key in an Authorization: Bearer header.
| Endpoint | Method | Purpose |
|---|---|---|
/api/site | GET | Returns address, space used, and file count. |
/api/files | GET | Lists every file with size and last modified time. |
/api/upload | POST | Uploads up to 20 files at a time. |
/api/delete | POST | Deletes a single file by its path. |
Sources: src/server.js:827-880, src/views.js:636-655
Conclusion
The Site File Manager combines standard file system operations with web-specific security needs. By enforcing path isolation and file-type restrictions, it provides a safe environment for hosting static homepages. Integration with tools like sharp for image optimization and a background quota tracking system ensures the platform remains performant and user-friendly for both manual and automated updates.