file-gateway

A web-based file explorer built with ASP.NET Core 9 and Blazor. Browse, download, and manage files on a server through a responsive web UI or programmatically via REST API.

Features

• Cookie-based authentication with login/logout
• Directory browsing and file downloading
• Signed download URLs for external client compatibility
• Rate limiting (configurable requests per window)
• Path safety validation (prevents directory traversal)
• Responsive web interface (Blazor + MudBlazor)
• Health check endpoint
• Cross-platform (Windows and Unix path support)
• Modular architecture (Core library + Server)

Prerequisites

• .NET 9 SDK

Quick Start

git clone <repository-url>
cd file-gateway
dotnet restore

Configure src/FileGateway.Server/appsettings.json (or use user secrets / environment variables):

{
  "FileGateway": {
    "RootDir": "/path/to/your/files"
  },
  "Auth": {
    "AuthUser": "admin",
    "AuthPass": "your-secure-password"
  },
  "RateLimit": {
    "WindowMs": 60000,
    "MaxRequests": 100
  },
  "DownloadToken": {
    "TokenTtlSeconds": 3600,
    "Secret": "a-random-secret-at-least-32-characters-long"
  }
}

Start the server:

dotnet run --project src/FileGateway.Server

Open http://localhost:3000 in your browser.

Configuration

All configuration is managed via appsettings.json, environment variables, or .NET user secrets.

Section	Key	Description	Default
FileGateway	RootDir	Root directory for file operations	Required
Auth	AuthUser	Username for authentication	Required
Auth	AuthPass	Password for authentication	Required
RateLimit	WindowMs	Rate limit window in milliseconds	60000
RateLimit	MaxRequests	Max requests per window	100
DownloadToken	TokenTtlSeconds	Download link expiration (seconds)	3600
DownloadToken	Secret	Secret key for signing download tokens	Required

Development

# Run with hot-reload
dotnet watch --project src/FileGateway.Server

# Build the solution
dotnet build

# Run the server
dotnet run --project src/FileGateway.Server

Testing

# Run all tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Check formatting
dotnet format --verify-no-changes

Docker

Using Docker Compose

Create a docker-compose.yml:

services:
  file-gateway:
    image: forgejo.fistach.ovh/bpeskiewicz/file-gateway:latest
    ports:
      - "3000:3000"
    environment:
      FileGateway__RootDir: /data
      Auth__AuthUser: admin
      Auth__AuthPass: your-secure-password
      DownloadToken__Secret: a-random-secret-at-least-32-characters-long
    volumes:
      - /path/to/your/files:/data:ro
    restart: unless-stopped

Run with:

docker compose up -d

Building Locally

docker build -t file-gateway .

docker run -d \
  -p 3000:3000 \
  -e FileGateway__RootDir=/data \
  -e Auth__AuthUser=admin \
  -e Auth__AuthPass=your-secure-password \
  -e DownloadToken__Secret=a-random-secret-at-least-32-characters-long \
  -v /path/to/your/files:/data:ro \
  file-gateway

API Endpoints

Method	Endpoint	Description
POST	/api/auth/login	Authenticate and receive cookie
GET/POST	/api/auth/logout	Clear authentication cookie
GET	/api/files	List directory contents
GET	/api/files/download	Download a file
GET	/api/files/links	Get signed download links
GET	/api/health	Application health and uptime

Project Structure

src/
  FileGateway.Server/    ASP.NET Core host, controllers, Blazor UI
  FileGateway.Core/      Shared models, security, business logic
tests/
  FileGateway.Server.Tests/
  FileGateway.Core.Tests/

License

MIT