@valentinkolb/filegate 0.0.1 → 0.0.5

package/README.md

@@ -1,429 +1,414 @@
 # Filegate
 
-A secure, high-performance file proxy server built with Bun + Hono + Zod.
+A secure file proxy server for building custom file management systems. Bring your own backend and frontend - Filegate handles the file operations.
 
-Features:
-- Streaming uploads/downloads
-- Directory download as ZIP
+```
+Browser/App          Your Backend            Filegate            Filesystem
+     |                    |                     |                    |
+     |  upload request    |                     |                    |
+     |------------------->|                     |                    |
+     |                    |  proxy to filegate  |                    |
+     |                    |-------------------->|                    |
+     |                    |                     |  write file        |
+     |                    |                     |------------------->|
+     |                    |                     |                    |
+     |                    |<--------------------|<-------------------|
+     |<-------------------|                     |                    |
+```
+
+Filegate is designed to work behind your backend, not as a public-facing service. Your backend handles authentication and authorization, then proxies requests to Filegate. This gives you full control over access logic while Filegate handles the complexity of streaming, chunked uploads, permissions, and security.
+
+## Features
+
+- Streaming uploads and downloads (no memory buffering)
 - Resumable chunked uploads with SHA-256 verification
+- Directory downloads as TAR archives
+- Unix file permissions (uid, gid, mode)
 - Glob-based file search
-- Type-safe client API with config objects
-- Browser-compatible utils for chunked uploads
-- OpenAPI documentation with Scalar UI
-- LLM-friendly markdown docs at `/llms.txt`
+- Type-safe client with full TypeScript support
+- OpenAPI documentation
 
 ## Quick Start
 
+### 1. Start Filegate with Docker
+
 ```bash
-export FILE_PROXY_TOKEN=your-secret-token
-export ALLOWED_BASE_PATHS=/export/homes,/export/groups
+docker run -d \
+  --name filegate \
+  -p 4000:4000 \
+  -e FILE_PROXY_TOKEN=your-secret-token \
+  -e ALLOWED_BASE_PATHS=/data \
+  -v /path/to/your/files:/data \
+  ghcr.io/valentinkolb/filegate:latest
+```
 
-bun run src/index.ts
+### 2. Install the Client
+
+```bash
+npm install @valentinkolb/filegate
 ```
 
-## Documentation
+### 3. Configure Environment
 
-- **Scalar UI:** http://localhost:4000/docs
-- **OpenAPI JSON:** http://localhost:4000/openapi.json
-- **LLM Markdown:** http://localhost:4000/llms.txt
+```bash
+export FILEGATE_URL=http://localhost:4000
+export FILEGATE_TOKEN=your-secret-token
+```
 
-## Configuration
+### 4. Upload a File
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `FILE_PROXY_TOKEN` | Yes | - | Bearer token for authentication |
-| `ALLOWED_BASE_PATHS` | Yes | - | Comma-separated allowed paths |
-| `REDIS_URL` | No | localhost:6379 | Redis connection URL (for chunked uploads) |
-| `PORT` | No | 4000 | Server port |
+```typescript
+import { filegate } from "@valentinkolb/filegate/client";
+
+const result = await filegate.upload.single({
+  path: "/data/uploads",
+  filename: "document.pdf",
+  data: fileBuffer,
+});
 
-**Size Limits:**
+if (result.ok) {
+  console.log("Uploaded:", result.data.path);
+}
+```
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MAX_UPLOAD_MB` | 500 | Maximum file size for uploads (simple + chunked) |
-| `MAX_DOWNLOAD_MB` | 5000 | Maximum file/directory size for downloads |
-| `MAX_CHUNK_SIZE_MB` | 50 | Maximum chunk size (server rejects larger chunks) |
+### 5. Download a File
 
-**Search:**
+```typescript
+import { filegate } from "@valentinkolb/filegate/client";
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SEARCH_MAX_RESULTS` | 100 | Max files returned by search |
-| `SEARCH_MAX_RECURSIVE_WILDCARDS` | 10 | Max `**` wildcards allowed in glob patterns (prevents DoS) |
+const result = await filegate.download({ path: "/data/uploads/document.pdf" });
 
-**Other:**
+if (result.ok) {
+  const blob = await result.data.blob();
+}
+```
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `UPLOAD_EXPIRY_HOURS` | 24 | Chunked upload expiry (resets on each chunk) |
-| `DISK_CLEANUP_INTERVAL_HOURS` | 6 | Interval to clean orphaned chunk files |
-| `DEV_UID_OVERRIDE` | - | Override file ownership UID (dev mode only) |
-| `DEV_GID_OVERRIDE` | - | Override file ownership GID (dev mode only) |
+## Architecture
 
-## API Endpoints
+Filegate follows a proxy architecture where your backend mediates all file operations:
 
-All `/files/*` endpoints require `Authorization: Bearer <token>`.
+```
++------------------+       +------------------+       +------------------+
+|                  |       |                  |       |                  |
+|   Your Client    |<----->|   Your Backend   |<----->|    Filegate      |
+|   (Browser/App)  |       |   (Auth, Logic)  |       |   (File Ops)     |
+|                  |       |                  |       |                  |
++------------------+       +------------------+       +------------------+
+                                                              |
+                                                              v
+                                                      +------------------+
+                                                      |                  |
+                                                      |   Filesystem     |
+                                                      |                  |
+                                                      +------------------+
+```
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/health` | Health check (public) |
-| GET | `/docs` | Scalar API docs (public) |
-| GET | `/openapi.json` | OpenAPI spec (public) |
-| GET | `/llms.txt` | LLM-friendly docs (public) |
-| GET | `/files/info` | File/directory info |
-| GET | `/files/content` | Download file or directory (ZIP) |
-| PUT | `/files/content` | Upload file |
-| POST | `/files/mkdir` | Create directory |
-| DELETE | `/files/delete` | Delete file/directory |
-| POST | `/files/move` | Move (same basepath) |
-| POST | `/files/copy` | Copy (same basepath) |
-| GET | `/files/search` | Glob search |
-| POST | `/files/upload/start` | Start/resume chunked upload |
-| POST | `/files/upload/chunk` | Upload chunk |
+**Your Client** handles the UI and user interactions. It communicates with your backend.
+
+**Your Backend** handles authentication, authorization, and business logic. It decides who can access what and proxies requests to Filegate.
+
+**Filegate** handles the actual file operations: reading, writing, streaming, chunked uploads, permissions. It only accepts requests with a valid token.
+
+This separation means you have full control over access patterns while Filegate handles the complexity of file operations.
 
-## Examples
+## Core Concepts
+
+### Base Paths
+
+Filegate restricts all file operations to explicitly allowed directories called "base paths". This is a security boundary - files outside these paths cannot be accessed.
 
-### Get Directory Info
 ```bash
-curl -H "Authorization: Bearer $TOKEN" \
-  "http://localhost:4000/files/info?path=/export/homes/alice&showHidden=false"
+ALLOWED_BASE_PATHS=/data/uploads,/data/exports
 ```
 
-### Upload File
-```bash
-curl -X PUT \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "X-File-Path: /export/homes/alice" \
-  -H "X-File-Name: report.pdf" \
-  -H "X-Owner-UID: 1000" \
-  -H "X-Owner-GID: 1000" \
-  -H "X-File-Mode: 600" \
-  --data-binary @report.pdf \
-  "http://localhost:4000/files/content"
+With this configuration:
+- `/data/uploads/file.txt` - allowed
+- `/data/exports/report.pdf` - allowed
+- `/home/user/file.txt` - forbidden
+- `/data/../etc/passwd` - forbidden (path traversal blocked)
+
+Symlinks that point outside base paths are also blocked.
+
+### File Ownership
+
+Filegate runs as root to set file ownership. When uploading files, you can specify Unix permissions:
+
+```typescript
+await client.upload.single({
+  path: "/data/uploads",
+  filename: "file.txt",
+  data: buffer,
+  uid: 1000,    // Owner user ID
+  gid: 1000,    // Owner group ID
+  mode: "644",  // Unix permissions (rw-r--r--)
+});
 ```
 
-### Search Files
-```bash
-curl -H "Authorization: Bearer $TOKEN" \
-  "http://localhost:4000/files/search?paths=/export/homes/alice,/export/groups/team&pattern=**/*.pdf"
+This is essential when Filegate manages files for multiple users on a shared filesystem.
+
+### Chunked Uploads
+
+For large files, use chunked uploads. They support:
+- Resume after connection failure
+- Progress tracking
+- Per-chunk checksum verification
+- Automatic assembly when complete
+
+```typescript
+// Start or resume upload
+const start = await client.upload.chunked.start({
+  path: "/data/uploads",
+  filename: "large-file.zip",
+  size: file.size,
+  checksum: "sha256:abc123...",  // Checksum of entire file
+  chunkSize: 5 * 1024 * 1024,    // 5MB chunks
+});
+
+// Upload each chunk
+for (let i = 0; i < start.data.totalChunks; i++) {
+  if (start.data.uploadedChunks.includes(i)) continue; // Skip already uploaded
+  
+  await client.upload.chunked.send({
+    uploadId: start.data.uploadId,
+    index: i,
+    data: chunkData,
+  });
+}
 ```
 
-### Chunked Upload
+Uploads automatically expire after 24 hours of inactivity.
+
+## Configuration
+
+All configuration is done through environment variables.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `FILE_PROXY_TOKEN` | Yes | - | Bearer token for API authentication |
+| `ALLOWED_BASE_PATHS` | Yes | - | Comma-separated list of allowed directories |
+| `PORT` | No | 4000 | Server port |
+| `MAX_UPLOAD_MB` | No | 500 | Maximum upload size in MB |
+| `MAX_DOWNLOAD_MB` | No | 5000 | Maximum download size in MB |
+| `MAX_CHUNK_SIZE_MB` | No | 50 | Maximum chunk size in MB |
+| `SEARCH_MAX_RESULTS` | No | 100 | Maximum search results returned |
+| `SEARCH_MAX_RECURSIVE_WILDCARDS` | No | 10 | Maximum `**` wildcards in glob patterns |
+| `UPLOAD_EXPIRY_HOURS` | No | 24 | Hours until incomplete uploads expire |
+| `UPLOAD_TEMP_DIR` | No | /tmp/filegate-uploads | Directory for temporary chunk storage |
+| `DISK_CLEANUP_INTERVAL_HOURS` | No | 6 | Interval for cleaning orphaned chunks |
+
+### Development Mode
+
+For local development without root permissions, you can override file ownership:
 
 ```bash
-# 1. Start upload
-curl -X POST \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "path": "/export/homes/alice",
-    "filename": "large.zip",
-    "size": 104857600,
-    "checksum": "sha256:abc123...",
-    "chunkSize": 10485760
-  }' \
-  "http://localhost:4000/files/upload/start"
-
-# 2. Upload chunks
-curl -X POST \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "X-Upload-Id: <uploadId>" \
-  -H "X-Chunk-Index: 0" \
-  -H "X-Chunk-Checksum: sha256:def456..." \
-  --data-binary @chunk0.bin \
-  "http://localhost:4000/files/upload/chunk"
-
-# Repeat for all chunks - auto-completes on last chunk
+DEV_UID_OVERRIDE=1000
+DEV_GID_OVERRIDE=1000
+```
+
+This applies the specified uid/gid instead of the requested values. Do not use in production.
+
+## Docker Compose Example
+
+```yaml
+services:
+  filegate:
+    image: ghcr.io/valentinkolb/filegate:latest
+    ports:
+      - "4000:4000"
+    environment:
+      FILE_PROXY_TOKEN: ${FILE_PROXY_TOKEN}
+      ALLOWED_BASE_PATHS: /data
+    volumes:
+      - ./data:/data
+      - filegate-chunks:/tmp/filegate-uploads
+
+volumes:
+  filegate-chunks:
 ```
 
 ## Client API
 
-Type-safe client for server-side usage. All methods use config objects for better readability.
+The client provides a type-safe interface for all Filegate operations.
 
 ### Installation
 
-```typescript
-import { Filegate } from "@valentinkolb/filegate/client";
-import { chunks, formatBytes } from "@valentinkolb/filegate/utils";
+```bash
+npm install @valentinkolb/filegate
 ```
 
-### Default Instance (via env vars)
+### Default Instance
 
-Set `FILEGATE_URL` and `FILEGATE_TOKEN`, then import the pre-configured instance:
+Set `FILEGATE_URL` and `FILEGATE_TOKEN` environment variables, then import the pre-configured client:
 
 ```typescript
 import { filegate } from "@valentinkolb/filegate/client";
 
-const info = await filegate.info({ path: "/export/homes/alice" });
+await filegate.info({ path: "/data/uploads" });
 ```
 
 ### Custom Instance
 
+For more control or multiple Filegate servers, create instances manually:
+
 ```typescript
 import { Filegate } from "@valentinkolb/filegate/client";
 
 const client = new Filegate({
   url: "http://localhost:4000",
-  token: "your-token",
+  token: "your-secret-token",
 });
 ```
 
-### Client Methods
+### Methods
 
 ```typescript
-// Get file/directory info
-const info = await client.info({ path: "/export/homes/alice", showHidden: true });
-
-// Download file (returns Response with streaming body)
-const file = await client.download({ path: "/export/homes/alice/report.pdf" });
-if (file.ok) {
-  const text = await file.data.text();
-  const buffer = await file.data.arrayBuffer();
-  // Or stream directly: file.data.body
-}
+// Get file or directory info
+await client.info({ path: "/data/file.txt", showHidden: false });
 
-// Download directory as ZIP
-const zip = await client.download({ path: "/export/homes/alice/documents" });
+// Download file (returns streaming Response)
+await client.download({ path: "/data/file.txt" });
 
-// Upload file (simple)
+// Download directory as TAR archive
+await client.download({ path: "/data/folder" });
+
+// Simple upload
 await client.upload.single({
-  path: "/export/homes/alice",
-  filename: "report.pdf",
-  data: fileData,
+  path: "/data/uploads",
+  filename: "file.txt",
+  data: buffer,
   uid: 1000,
   gid: 1000,
   mode: "644",
 });
 
-// Upload file (chunked) - for large files
-const startResult = await client.upload.chunked.start({
-  path: "/export/homes/alice",
-  filename: "large.zip",
-  size: file.size,
-  checksum: "sha256:...",
-  chunkSize: 5 * 1024 * 1024,
-  uid: 1000,
-  gid: 1000,
-});
-
-// Send chunks
-await client.upload.chunked.send({
-  uploadId: startResult.data.uploadId,
-  index: 0,
-  data: chunkData,
-  checksum: "sha256:...",
-});
+// Chunked upload
+await client.upload.chunked.start({ ... });
+await client.upload.chunked.send({ ... });
 
 // Create directory
-await client.mkdir({ path: "/export/homes/alice/new-folder", mode: "750" });
+await client.mkdir({ path: "/data/new-folder", mode: "755" });
+
+// Delete file or directory
+await client.delete({ path: "/data/old-file.txt" });
 
-// Move/copy (within same basepath)
-await client.move({ from: "/export/homes/alice/old.txt", to: "/export/homes/alice/new.txt" });
-await client.copy({ from: "/export/homes/alice/file.txt", to: "/export/homes/alice/backup.txt" });
+// Move (within same base path)
+await client.move({ from: "/data/old.txt", to: "/data/new.txt" });
 
-// Delete
-await client.delete({ path: "/export/homes/alice/trash" });
+// Copy (within same base path)
+await client.copy({ from: "/data/file.txt", to: "/data/backup.txt" });
 
 // Search with glob patterns
-const results = await client.glob({
-  paths: ["/export/homes/alice", "/export/groups/team"],
+await client.glob({
+  paths: ["/data/uploads"],
   pattern: "**/*.pdf",
-  showHidden: false,
-  limit: 100,
+  limit: 50,
 });
 ```
 
-## Browser Utils
+### Response Format
 
-Browser-compatible utilities for chunked uploads. Framework-agnostic with reactive state management.
-
-### Basic Usage
+All methods return a discriminated union:
 
 ```typescript
-import { chunks, formatBytes } from "@valentinkolb/filegate/utils";
+type Response<T> = 
+  | { ok: true; data: T }
+  | { ok: false; error: string; status: number };
 
-// Prepare upload (calculates checksum and chunk info)
-const upload = await chunks.prepare({ file, chunkSize: 5 * 1024 * 1024 });
+const result = await client.info({ path: "/data/file.txt" });
 
-// Access properties
-upload.file          // Original File/Blob
-upload.fileSize      // Total size in bytes
-upload.chunkSize     // Chunk size in bytes
-upload.totalChunks   // Number of chunks
-upload.checksum      // "sha256:..." of entire file
-
-// Format bytes for display
-formatBytes({ bytes: upload.fileSize });  // "52.43 MB"
+if (result.ok) {
+  console.log(result.data.size);
+} else {
+  console.error(result.error); // "not found", "path not allowed", etc.
+}
 ```
 
-### State Management
+## Browser Utilities
 
-```typescript
-// Subscribe to state changes (framework-agnostic)
-const unsubscribe = upload.subscribe((state) => {
-  console.log(`${state.percent}% - ${state.status}`);
-  // state: { uploaded: number, total: number, percent: number, status: "pending" | "uploading" | "completed" | "error" }
-});
-
-// Mark chunk as completed
-upload.complete({ index: 0 });
-
-// Reset state
-upload.reset();
-
-// Unsubscribe when done
-unsubscribe();
-```
-
-### Chunk Access
+For browser-based chunked uploads, use the utils package:
 
 ```typescript
-// Get specific chunk (sync, returns Blob)
-const chunk = upload.get({ index: 0 });
+import { chunks, formatBytes } from "@valentinkolb/filegate/utils";
 
-// Calculate chunk checksum
-const hash = await upload.hash({ data: chunk });
+// Prepare a file for chunked upload
+const upload = await chunks.prepare({
+  file: fileInput.files[0],
+  chunkSize: 5 * 1024 * 1024,
+});
 
-// Iterate over all chunks
-for await (const { index, data, total } of upload) {
-  console.log(`Chunk ${index + 1}/${total}`);
-}
-```
+console.log(upload.checksum);    // "sha256:..."
+console.log(upload.totalChunks); // Number of chunks
+console.log(formatBytes({ bytes: upload.fileSize })); // "52.4 MB"
 
-### Upload Helpers
+// Subscribe to progress updates
+upload.subscribe((state) => {
+  console.log(`${state.percent}% - ${state.status}`);
+});
 
-```typescript
-// Send single chunk with retry
-await upload.send({
-  index: 0,
+// Upload all chunks with retry and concurrency
+await upload.sendAll({
+  skip: alreadyUploadedChunks,
   retries: 3,
+  concurrency: 3,
   fn: async ({ index, data }) => {
     await fetch("/api/upload/chunk", {
       method: "POST",
-      headers: { "X-Chunk-Index": String(index) },
+      headers: {
+        "X-Upload-Id": uploadId,
+        "X-Chunk-Index": String(index),
+      },
       body: data,
     });
   },
 });
-
-// Send all chunks (with skip for resume, concurrency, retries)
-await upload.sendAll({
-  skip: [0, 1],      // Already uploaded chunks (from resume)
-  retries: 3,
-  concurrency: 3,    // Parallel uploads
-  fn: async ({ index, data }) => {
-    await fetch("/api/upload/chunk", { ... });
-  },
-});
 ```
 
-### Complete Example (Browser)
-
-```typescript
-import { chunks } from "@valentinkolb/filegate/utils";
+## API Endpoints
 
-async function uploadFile(file: File, targetPath: string, onProgress?: (state) => void) {
-  const upload = await chunks.prepare({ file, chunkSize: 5 * 1024 * 1024 });
-  
-  if (onProgress) upload.subscribe(onProgress);
-  
-  // 1. Start/Resume upload
-  const { uploadId, uploadedChunks, completed } = await fetch("/api/upload/start", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      path: targetPath,
-      filename: file.name,
-      size: upload.fileSize,
-      checksum: upload.checksum,
-      chunkSize: upload.chunkSize,
-    }),
-  }).then(r => r.json());
-  
-  if (completed) return; // Already done
-  
-  // 2. Upload all chunks (skipping already uploaded)
-  await upload.sendAll({
-    skip: uploadedChunks,
-    retries: 3,
-    fn: async ({ index, data }) => {
-      await fetch("/api/upload/chunk", {
-        method: "POST",
-        headers: {
-          "X-Upload-Id": uploadId,
-          "X-Chunk-Index": String(index),
-          "X-Chunk-Checksum": await upload.hash({ data }),
-        },
-        body: data,
-      });
-    },
-  });
-}
+All `/files/*` endpoints require `Authorization: Bearer <token>`.
 
-// Usage with React
-function UploadButton() {
-  const [progress, setProgress] = useState({ percent: 0, status: "pending" });
-  
-  const handleUpload = async (file: File) => {
-    await uploadFile(file, "/documents", setProgress);
-  };
-  
-  return <div>{progress.percent}% - {progress.status}</div>;
-}
-```
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| GET | `/docs` | OpenAPI documentation (Scalar UI) |
+| GET | `/openapi.json` | OpenAPI specification |
+| GET | `/llms.txt` | LLM-friendly markdown documentation |
+| GET | `/files/info` | Get file or directory info |
+| GET | `/files/content` | Download file or directory (TAR) |
+| PUT | `/files/content` | Upload file |
+| POST | `/files/mkdir` | Create directory |
+| DELETE | `/files/delete` | Delete file or directory |
+| POST | `/files/move` | Move file or directory |
+| POST | `/files/copy` | Copy file or directory |
+| GET | `/files/search` | Search with glob pattern |
+| POST | `/files/upload/start` | Start or resume chunked upload |
+| POST | `/files/upload/chunk` | Upload a chunk |
 
-### Streaming Proxy (Server-Side)
+## Security
 
-The download response streams directly - perfect for proxying without buffering:
+Filegate implements multiple security layers:
 
-```typescript
-// In your proxy server (e.g., with Hono, Express, etc.)
-app.get("/api/files/download", async (c) => {
-  const path = c.req.query("path");
-  
-  // Get streaming response from Filegate
-  const response = await client.download({ path });
-  
-  if (!response.ok) {
-    return c.json({ error: response.error }, response.status);
-  }
-  
-  // Stream directly to client - no buffering!
-  return new Response(response.data.body, {
-    headers: {
-      "Content-Type": response.data.headers.get("Content-Type") || "application/octet-stream",
-      "Content-Disposition": response.data.headers.get("Content-Disposition") || "",
-    },
-  });
-});
-```
+- **Path validation**: All paths are validated against allowed base paths
+- **Symlink protection**: Symlinks pointing outside base paths are blocked
+- **Path traversal prevention**: Sequences like `../` are normalized and checked
+- **Size limits**: Configurable limits for uploads, downloads, and chunks
+- **Search limits**: Glob pattern complexity is limited to prevent DoS
+- **Secure headers**: X-Frame-Options, X-Content-Type-Options, etc.
 
-## Security
+## Development
 
-- Path validation with symlink protection
-- Base path escape prevention
-- Same-basepath enforcement for move/copy
-- SHA-256 checksum verification
-- Configurable upload/download size limits
-- Glob pattern limits (max length 500 chars, configurable recursive wildcard limit)
-- Security headers (X-Frame-Options, X-Content-Type-Options, etc.)
+```bash
+# Install dependencies
+bun install
 
-## Testing
+# Run server
+FILE_PROXY_TOKEN=dev ALLOWED_BASE_PATHS=/tmp bun run src/index.ts
 
-```bash
-# Run unit tests
+# Run tests
 bun run test:unit
-
-# Run integration tests (requires Docker)
 bun run test:integration:run
-
-# Run all tests
-bun run test:all
 ```
 
-## Tech Stack
+## License
 
-- **Runtime:** Bun
-- **Framework:** Hono
-- **Validation:** Zod
-- **Docs:** hono-openapi + Scalar
+MIT

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@valentinkolb/filegate",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "description": "Secure, high-performance file proxy server with streaming uploads, chunked uploads, and TAR downloads",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/valentinkolb/filegate.git"
+    "url": "https://github.com/ValentinKolb/filegate.git"
   },
   "keywords": [
     "file-server",

package/src/handlers/upload.ts

@@ -1,7 +1,6 @@
 import { Hono } from "hono";
 import { describeRoute } from "hono-openapi";
-import { redis } from "bun";
-import { mkdir, readdir, rm, stat, rename } from "node:fs/promises";
+import { mkdir, readdir, rm, stat, rename, readFile, writeFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { validatePath } from "../lib/path";
 import { applyOwnership, type Ownership } from "../lib/ownership";
@@ -25,12 +24,10 @@ const computeUploadId = (path: string, filename: string, checksum: string): stri
   return hasher.digest("hex").slice(0, 16);
 };
 
-// Single Redis key per upload
-const metaKey = (id: string) => `filegate:upload:${id}`;
-
 // Chunk storage paths
 const chunksDir = (id: string) => join(config.uploadTempDir, id);
 const chunkPath = (id: string, idx: number) => join(chunksDir(id), String(idx));
+const metaPath = (id: string) => join(chunksDir(id), "meta.json");
 
 type UploadMeta = {
   uploadId: string;
@@ -41,26 +38,35 @@ type UploadMeta = {
   chunkSize: number;
   totalChunks: number;
   ownership: Ownership | null;
+  createdAt: number; // Unix timestamp for expiry check
 };
 
 const saveMeta = async (meta: UploadMeta): Promise<void> => {
-  await redis.set(metaKey(meta.uploadId), JSON.stringify(meta), "EX", config.uploadExpirySecs);
+  await mkdir(chunksDir(meta.uploadId), { recursive: true });
+  await writeFile(metaPath(meta.uploadId), JSON.stringify(meta));
 };
 
 const loadMeta = async (id: string): Promise<UploadMeta | null> => {
-  const data = await redis.get(metaKey(id));
-  return data ? (JSON.parse(data) as UploadMeta) : null;
+  try {
+    const data = await readFile(metaPath(id), "utf-8");
+    return JSON.parse(data) as UploadMeta;
+  } catch {
+    return null;
+  }
 };
 
-const refreshExpiry = async (id: string): Promise<void> => {
-  await redis.expire(metaKey(id), config.uploadExpirySecs);
+const refreshExpiry = async (id: string, meta: UploadMeta): Promise<void> => {
+  // Update createdAt to extend expiry
+  meta.createdAt = Date.now();
+  await saveMeta(meta);
 };
 
-// Get uploaded chunks from filesystem instead of Redis
+// Get uploaded chunks from filesystem
 const getUploadedChunks = async (id: string): Promise<number[]> => {
   try {
     const files = await readdir(chunksDir(id));
     return files
+      .filter((f) => f !== "meta.json")
       .map((f) => parseInt(f, 10))
       .filter((n) => !isNaN(n))
       .sort((a, b) => a - b);
@@ -70,7 +76,7 @@ const getUploadedChunks = async (id: string): Promise<number[]> => {
 };
 
 const cleanupUpload = async (id: string): Promise<void> => {
-  await Promise.all([redis.del(metaKey(id)), rm(chunksDir(id), { recursive: true }).catch(() => {})]);
+  await rm(chunksDir(id), { recursive: true }).catch(() => {});
 };
 
 const assembleFile = async (meta: UploadMeta): Promise<string | null> => {
@@ -155,8 +161,8 @@ app.post(
     // Check for existing upload (resume)
     const existingMeta = await loadMeta(uploadId);
     if (existingMeta) {
-      // Refresh TTL on resume
-      await refreshExpiry(uploadId);
+      // Refresh expiry on resume
+      await refreshExpiry(uploadId, existingMeta);
       // Get chunks from filesystem
       const uploadedChunks = await getUploadedChunks(uploadId);
       return c.json({
@@ -186,9 +192,9 @@ app.post(
       chunkSize,
       totalChunks,
       ownership,
+      createdAt: Date.now(),
     };
 
-    await mkdir(chunksDir(uploadId), { recursive: true });
     await saveMeta(meta);
 
     return c.json({
@@ -306,23 +312,26 @@ app.post(
   },
 );
 
-// Cleanup orphaned chunk directories (Redis keys expired but files remain)
+// Cleanup expired upload directories
 export const cleanupOrphanedChunks = async () => {
   try {
     const dirs = await readdir(config.uploadTempDir);
     let cleaned = 0;
+    const now = Date.now();
+    const expiryMs = config.uploadExpirySecs * 1000;
 
     for (const dir of dirs) {
-      // Check if upload still exists in Redis
-      const exists = await redis.exists(metaKey(dir));
-      if (!exists) {
+      const meta = await loadMeta(dir);
+
+      // Remove if no meta or expired
+      if (!meta || now - meta.createdAt > expiryMs) {
         await rm(chunksDir(dir), { recursive: true }).catch(() => {});
         cleaned++;
       }
     }
 
     if (cleaned > 0) {
-      console.log(`[Filegate] Cleaned up ${cleaned} orphaned chunk director${cleaned === 1 ? "y" : "ies"}`);
+      console.log(`[Filegate] Cleaned up ${cleaned} expired upload${cleaned === 1 ? "" : "s"}`);
     }
   } catch {
     // Directory doesn't exist yet

package/src/index.ts

@@ -22,7 +22,6 @@ if (config.isDev) {
 
 console.log(`[Filegate] ALLOWED_BASE_PATHS: ${config.allowedPaths.join(", ")}`);
 console.log(`[Filegate] MAX_UPLOAD_MB: ${config.maxUploadBytes / 1024 / 1024}`);
-console.log(`[Filegate] REDIS_URL: ${process.env.REDIS_URL ?? "redis://localhost:6379 (default)"}`);
 console.log(`[Filegate] PORT: ${config.port}`);
 
 // Periodic disk cleanup for orphaned chunks (every 6h by default)