@valentinkolb/filegate 0.0.4 → 0.0.6

package/README.md

@@ -1,429 +1,393 @@
 # Filegate
 
-A secure, high-performance file proxy server built with Bun + Hono + Zod.
+Secure file proxy for building custom file management systems. Streaming uploads, chunked transfers, Unix permissions.
 
-Features:
-- Streaming uploads/downloads
-- Directory download as ZIP
+```
+Browser/App          Your Backend            Filegate            Filesystem
+     |                    |                     |                    |
+     |  upload request    |                     |                    |
+     |------------------->|                     |                    |
+     |                    |  proxy to filegate  |                    |
+     |                    |-------------------->|                    |
+     |                    |                     |  write file        |
+     |                    |                     |------------------->|
+     |                    |                     |                    |
+     |                    |<--------------------|<-------------------|
+     |<-------------------|                     |                    |
+```
+
+Filegate runs behind your backend, not as a public-facing service. Your backend handles authentication and authorization, then proxies requests to Filegate. You control access logic - Filegate handles file operations.
+
+## 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
+- Minimal dependencies (Hono, Zod - no database required)
 
 ## Quick Start
 
-```bash
-export FILE_PROXY_TOKEN=your-secret-token
-export ALLOWED_BASE_PATHS=/export/homes,/export/groups
+### 1. Start Filegate with Docker
 
-bun run src/index.ts
+```bash
+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
 ```
 
-## Documentation
+### 2. Install the Client
 
-- **Scalar UI:** http://localhost:4000/docs
-- **OpenAPI JSON:** http://localhost:4000/openapi.json
-- **LLM Markdown:** http://localhost:4000/llms.txt
+```bash
+npm install @valentinkolb/filegate
+```
 
-## Configuration
+### 3. Configure Environment
 
-| 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 |
+```bash
+export FILEGATE_URL=http://localhost:4000
+export FILEGATE_TOKEN=your-secret-token
+```
 
-**Size Limits:**
+### 4. Upload a File
 
-| 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) |
+```typescript
+import { filegate } from "@valentinkolb/filegate/client";
 
-**Search:**
+const result = await filegate.upload.single({
+  path: "/data/uploads",
+  filename: "document.pdf",
+  data: fileBuffer,
+});
 
-| 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) |
+if (result.ok) {
+  console.log("Uploaded:", result.data.path);
+}
+```
 
-**Other:**
+### 5. Download a File
 
-| 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) |
+```typescript
+import { filegate } from "@valentinkolb/filegate/client";
 
-## API Endpoints
+const result = await filegate.download({ path: "/data/uploads/document.pdf" });
 
-All `/files/*` endpoints require `Authorization: Bearer <token>`.
+if (result.ok) {
+  const blob = await result.data.blob();
+}
+```
 
-| 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 |
+## Core Concepts
+
+### Base Paths
 
-## Examples
+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 can set Unix file ownership on uploaded files:
+
+```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"
+If ownership is not specified, files are created with the user running Filegate (typically root in Docker).
+
+Filegate does not validate whether the specified uid/gid exists on the system, nor does it verify that the requesting user matches the specified ownership. Your backend is responsible for this validation.
+
+This feature is intended for scenarios like NFS shares exposed through Filegate, where preserving the original permission structure is required.
+
+### Chunked Uploads
+
+For large files, use chunked uploads. They support:
+- Resume after connection failure
+- Progress tracking
+- Per-chunk checksum verification
+- Automatic assembly when complete
+
+The [Browser Utilities](#browser-utilities) help with checksum calculation, chunking, and progress tracking. They work both in the browser and on the server.
+
+```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 file (returns streaming Response)
+await client.download({ path: "/data/file.txt" });
 
-// Download directory as ZIP
-const zip = await client.download({ path: "/export/homes/alice/documents" });
+// Download directory as TAR archive
+await client.download({ path: "/data/folder" });
 
-// Upload file (simple)
+// 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" });
 
-// 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" });
+// Delete file or directory
+await client.delete({ path: "/data/old-file.txt" });
 
-// Delete
-await client.delete({ path: "/export/homes/alice/trash" });
+// Move (within same base path)
+await client.move({ from: "/data/old.txt", to: "/data/new.txt" });
+
+// 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
-
-Browser-compatible utilities for chunked uploads. Framework-agnostic with reactive state management.
+### Response Format
 
-### Basic Usage
+All methods return a discriminated union:
 
 ```typescript
-import { chunks, formatBytes } from "@valentinkolb/filegate/utils";
-
-// Prepare upload (calculates checksum and chunk info)
-const upload = await chunks.prepare({ file, chunkSize: 5 * 1024 * 1024 });
+type Response<T> = 
+  | { ok: true; data: T }
+  | { ok: false; error: string; status: number };
 
-// 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
+const result = await client.info({ path: "/data/file.txt" });
 
-// 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
-
-```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();
-```
+## Browser Utilities
 
-### Chunk Access
+Utilities for chunked uploads that work both in the browser and on the server. They handle file chunking, SHA-256 checksum calculation, progress tracking, and retry logic.
 
 ```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,7 +1,7 @@
 {
   "name": "@valentinkolb/filegate",
-  "version": "0.0.4",
-  "description": "Secure, high-performance file proxy server with streaming uploads, chunked uploads, and TAR downloads",
+  "version": "0.0.6",
+  "description": "Secure file proxy for building custom file management systems. Streaming uploads, chunked transfers, Unix permissions.",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

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

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
 import { Scalar } from "@scalar/hono-api-reference";
 import { generateSpecs } from "hono-openapi";
 import { createMarkdownFromOpenApi } from "@scalar/openapi-to-markdown";
@@ -22,7 +23,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)
@@ -70,6 +70,11 @@ app.notFound((c) => c.json({ error: "not found" }, 404));
 
 // Error handler
 app.onError((err, c) => {
+  // HTTPException (from bearerAuth, etc.) - return the proper response
+  if (err instanceof HTTPException) {
+    return err.getResponse();
+  }
+
   console.error("[Filegate] Error:", err);
   return c.json({ error: "internal error" }, 500);
 });