@valentinkolb/filegate 2.4.0 → 2.5.3

package/README.md

@@ -1,569 +1,166 @@
-# Filegate
+# @valentinkolb/filegate
 
-Secure file proxy for building custom file management systems. Streaming uploads, chunked transfers, Unix permissions.
+TypeScript client for Filegate. Use it from trusted server runtimes to call the
+Filegate REST API, and from browsers only with scoped direct upload/download
+URLs minted by your application server.
 
-```
-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 with full TypeScript support
-- OpenAPI documentation
-- Minimal dependencies (Hono, Zod - no database required)
+Filegate keeps files as normal Linux files on configured mounts. The client
+covers path and ID lookup, direct URLs, upload sessions, transfers, search,
+activity, and stats.
 
-## Quick Start
-
-### 1. Start Filegate with Docker
+## Install
 
 ```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
+npm i @valentinkolb/filegate
 ```
 
-### 2. Install the Client
-
-```bash
-npm install @valentinkolb/filegate
-```
+## Server client
 
-### 3. Configure Environment
+Use the default instance when `FILEGATE_URL` and `FILEGATE_TOKEN` are available
+in the server runtime:
 
-```bash
-export FILEGATE_URL=http://localhost:4000
-export FILEGATE_TOKEN=your-secret-token
-```
-
-### 4. Upload a File
-
-```typescript
+```ts
 import { filegate } from "@valentinkolb/filegate/client";
 
-const result = await filegate.upload.single({
-  path: "/data/uploads",
-  filename: "document.pdf",
-  data: fileBuffer,
-});
+process.env.FILEGATE_URL = "http://127.0.0.1:8080";
+process.env.FILEGATE_TOKEN = "dev-token";
 
-if (result.ok) {
-  console.log("Uploaded:", result.data.path);
-}
+const roots = await filegate.paths.get();
+const caps = await filegate.capabilities.get();
 ```
 
-### 5. Download a File
-
-```typescript
-import { filegate } from "@valentinkolb/filegate/client";
-
-const result = await filegate.download({ path: "/data/uploads/document.pdf" });
+Use an explicit instance for dependency injection:
 
-if (result.ok) {
-  const blob = await result.data.blob();
-}
+```ts
+import { Filegate } from "@valentinkolb/filegate/client";
 
-// Open in browser instead of downloading
-const preview = await filegate.download({
-  path: "/data/uploads/image.png",
-  inline: true,
+const fg = new Filegate({
+  baseUrl: "https://filegate.internal.example",
+  token: "<filegate-token>",
+  fetchImpl: fetch,
 });
-```
-
-## 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.
-
-```bash
-ALLOWED_BASE_PATHS=/data/uploads,/data/exports
+const node = await fg.paths.get("photos/2026");
 ```
 
-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)
+The client namespaces match the API surface:
 
-Symlinks that point outside base paths are also blocked.
+| Namespace | Meaning |
+| --- | --- |
+| `paths` | Path-based lookup, upload, and directory listing. |
+| `nodes` | ID-based metadata, content, mkdir, delete, and metadata edits. |
+| `uploads` | One-shot direct upload URLs and resumable upload sessions. |
+| `downloads` | Scoped direct download URLs. |
+| `transfers` | Move and copy operations. |
+| `search` | Indexed path search. |
+| `index` | Index stats and rescan operations. |
+| `stats` | Runtime, mount, cache, filesystem, and process stats. |
+| `capabilities` | Server upload/download limits for adaptive clients. |
+| `versions` | File version history on supported mounts. |
+| `activity` | Recent API activity from the bounded server ring buffer. |
 
-### Auto-Create Parent Directories
+## Browser uploads
 
-When uploading files, Filegate automatically creates any missing parent directories. This simplifies folder uploads where nested structures need to be created on-the-fly:
+Do not expose the Filegate bearer token to browser code. The browser should ask
+your application server for permission to upload. The application server then
+creates direct Filegate upload URLs or direct upload sessions and returns the
+scoped credentials to the browser.
 
-```typescript
-// Parent directories /data/new/nested/path will be created automatically
-await client.upload.single({
-  path: "/data/new/nested/path",
-  filename: "file.txt",
-  data: buffer,
-});
-```
-
-This applies to both simple uploads and chunked uploads.
-
-### File Ownership
-
-Filegate can set Unix file ownership on uploaded files:
+```ts
+import { upload } from "@valentinkolb/filegate/client";
 
-```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--)
+await upload({
+  files,
+  path: "photos/inbox",
+  allow: async (request) => {
+    const response = await fetch("/api/filegate/uploads/allow", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request),
+    });
+    return response.json();
+  },
+  onEvent: (event) => {
+    console.log(event.type, event);
+  },
 });
 ```
 
-If ownership is not specified, files are created with the user running Filegate (typically root in Docker).
+The high-level helper uses the transfer shape from the allow response. Small
+files can use direct one-shot URLs. Larger files can use resumable sessions
+with parallel segment uploads. Conflict handling is explicit; `skip-existing`
+is the default.
 
-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.
+For a single direct upload URL:
 
-This feature is intended for scenarios like NFS shares exposed through Filegate, where preserving the original permission structure is required.
+```ts
+import { uploadDirect } from "@valentinkolb/filegate/client";
 
-### Transfer (Move/Copy)
-
-The `transfer` endpoint handles both moving and copying files or directories:
-
-```typescript
-// Move (rename) a file - same base path only
-await client.transfer({
-  from: "/data/old-name.txt",
-  to: "/data/new-name.txt",
-  mode: "move",
-});
-
-// Copy within same base path - no ownership required
-await client.transfer({
-  from: "/data/file.txt",
-  to: "/data/backup/file.txt",
-  mode: "copy",
-});
-
-// Copy across different base paths - ownership required
-await client.transfer({
-  from: "/data/file.txt",
-  to: "/backup/file.txt",
-  mode: "copy",
-  uid: 1000,
-  gid: 1000,
-  fileMode: "644",
-});
-
-// Allow overwriting existing files (default: false)
-await client.transfer({
-  from: "/data/new-file.txt",
-  to: "/data/existing-file.txt",
-  mode: "copy",
-  ensureUniqueName: false,  // Overwrite if target exists
+await uploadDirect(uploadUrlFromYourServer, file, {
+  onSuccess: ({ node }) => console.log(node.id),
 });
 ```
 
-**Rules:**
-- `mode: "move"` - Only within the same base path (uses filesystem rename)
-- `mode: "copy"` without ownership - Only within the same base path
-- `mode: "copy"` with ownership - Allows cross-base copying (ownership is applied recursively)
-- Both operations work recursively on directories
-- `ensureUniqueName: true` (default) - Appends `-01`, `-02`, etc. if target exists
-- `ensureUniqueName: false` - Overwrites existing target file
-
-### Thumbnails
+## Browser downloads
 
-Filegate can generate image thumbnails on-the-fly using Sharp. No caching - thumbnails are generated per request (typically 5-20ms).
+Mint the direct download URL on your application server and redirect the
+browser:
 
-```typescript
-// Get a 200x200 cover thumbnail (default)
-const result = await client.thumbnail.image({
-  path: "/data/photos/vacation.jpg",
+```ts
+const direct = await fg.downloads.createDirectURL({
+  nodeId: "<node-id>",
+  expiresInSeconds: 5 * 60,
 });
 
-if (result.ok) {
-  const blob = await result.data.blob();
-  // Use as image source
-}
-
-// Customized thumbnail
-const result = await client.thumbnail.image({
-  path: "/data/photos/vacation.jpg",
-  width: 400,
-  height: 300,
-  fit: "contain",      // Fit within bounds, preserve aspect ratio
-  format: "webp",      // Output format
-  quality: 90,         // Higher quality
-});
-
-// Smart cropping with attention detection
-const result = await client.thumbnail.image({
-  path: "/data/photos/portrait.jpg",
-  width: 150,
-  height: 150,
-  fit: "cover",
-  position: "attention",  // Focus on interesting areas
-});
-```
-
-**Options:**
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `width` | 200 | Width in pixels (max 2000) |
-| `height` | 200 | Height in pixels (max 2000) |
-| `fit` | `cover` | `cover`, `contain`, `fill`, `inside`, `outside` |
-| `position` | `center` | Crop position: `center`, `top`, `bottom`, `left`, `right`, `entropy`, `attention` |
-| `format` | `webp` | Output: `webp`, `jpeg`, `png`, `avif` |
-| `quality` | 80 | Quality 1-100 |
-
-**Fit modes:**
-- `cover` - Fill the box, crop excess (best for uniform grids)
-- `contain` - Fit within box, preserve aspect ratio (may have letterboxing)
-- `fill` - Stretch to exact size (distorts)
-- `inside` - Like contain, but never upscale
-- `outside` - Like cover, but never downscale
-
-**Supported input formats:** JPEG, PNG, WebP, AVIF, TIFF, GIF, SVG
-
-**Caching:** Thumbnails include `ETag`, `Last-Modified`, and `Cache-Control: immutable` headers. Simply pass through the response:
-
-```typescript
-const result = await client.thumbnail.image({ path: "/data/photo.jpg" });
-if (!result.ok) return c.json({ error: result.error }, result.status);
-
-return result.data; // Response with all headers
+return Response.redirect(direct.downloadUrl, 303);
 ```
 
-### Chunked Uploads
+Direct file downloads support `GET`, `HEAD`, and byte ranges. Directory
+downloads stream tar archives.
 
-For large files, use chunked uploads. They support:
-- Resume after connection failure
-- Progress tracking
-- Per-chunk checksum verification
-- Automatic assembly when complete
+## Resumable sessions
 
-The [Browser Utilities](#browser-utilities) help with checksum calculation, chunking, and progress tracking. They work both in the browser and on the server.
+Use upload sessions when you need resumable, parallel uploads with explicit
+commit:
 
-```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
+```ts
+const session = await fg.uploads.sessions.create({
+  path: "videos/input.mov",
+  size,
+  checksum,
+  segmentSize: 16 * 1024 * 1024,
+  onConflict: "error",
 });
 
-// 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,
+for (const segment of session.segments) {
+  await fg.uploads.sessions.segments.put({
+    sessionId: session.id,
+    index: segment.index,
+    body: segmentBody,
+    checksum: segmentChecksum,
   });
 }
-```
-
-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
-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
-
-The client provides a type-safe interface for all Filegate operations.
-
-### Installation
-
-```bash
-npm install @valentinkolb/filegate
-```
-
-### Default Instance
-
-Set `FILEGATE_URL` and `FILEGATE_TOKEN` environment variables, then import the pre-configured client:
-
-```typescript
-import { filegate } from "@valentinkolb/filegate/client";
-
-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-secret-token",
-});
-```
-
-### Methods
-
-```typescript
-// Get file or directory info
-await client.info({ path: "/data/file.txt", showHidden: false });
-
-// Get directory info with recursive sizes (slower)
-await client.info({ path: "/data/uploads", computeSizes: true });
-
-// Download file (returns streaming Response)
-await client.download({ path: "/data/file.txt" });
-
-// Download and open in browser (inline)
-await client.download({ path: "/data/image.png", inline: true });
-
-// Download directory as TAR archive
-await client.download({ path: "/data/folder" });
-
-// Simple upload
-await client.upload.single({
-  path: "/data/uploads",
-  filename: "file.txt",
-  data: buffer,
-  uid: 1000,
-  gid: 1000,
-  mode: "644",
-});
-
-// Chunked upload
-await client.upload.chunked.start({ ... });
-await client.upload.chunked.send({ ... });
-
-// Create directory
-await client.mkdir({ path: "/data/new-folder", mode: "755" });
-
-// Delete file or directory
-await client.delete({ path: "/data/old-file.txt" });
-
-// Transfer: Move or copy files/directories
-await client.transfer({
-  from: "/data/old.txt",
-  to: "/data/new.txt",
-  mode: "move",  // or "copy"
-});
-
-// Transfer with ownership (required for cross-base copy)
-await client.transfer({
-  from: "/data/file.txt",
-  to: "/backup/file.txt",
-  mode: "copy",
-  uid: 1000,
-  gid: 1000,
-  fileMode: "644",
-  dirMode: "755",
-  ensureUniqueName: true,  // default: append -01, -02 if target exists
-});
-
-// Search files with glob patterns
-await client.glob({
-  paths: ["/data/uploads"],
-  pattern: "**/*.pdf",
-  limit: 50,
-});
-
-// Search directories only
-await client.glob({
-  paths: ["/data"],
-  pattern: "**/*",
-  files: false,
-  directories: true,
-});
-
-// Search both files and directories
-await client.glob({
-  paths: ["/data"],
-  pattern: "**/*",
-  directories: true,
-});
-
-// Generate image thumbnail
-await client.thumbnail.image({
-  path: "/data/photo.jpg",
-  width: 200,
-  height: 200,
-  fit: "cover",
-  position: "center",
-  format: "webp",
-  quality: 80,
-});
-```
-
-### Response Format
-
-All methods return a discriminated union:
-
-```typescript
-type Response<T> = 
-  | { ok: true; data: T }
-  | { ok: false; error: string; status: number };
-
-const result = await client.info({ path: "/data/file.txt" });
-
-if (result.ok) {
-  console.log(result.data.size);
-} else {
-  console.error(result.error); // "not found", "path not allowed", etc.
-}
-```
-
-## Browser Utilities
 
-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
-import { chunks, formatBytes } from "@valentinkolb/filegate/utils";
-
-// Prepare a file for chunked upload
-const upload = await chunks.prepare({
-  file: fileInput.files[0],
-  chunkSize: 5 * 1024 * 1024,
-});
-
-console.log(upload.checksum);    // "sha256:..."
-console.log(upload.totalChunks); // Number of chunks
-console.log(formatBytes({ bytes: upload.fileSize })); // "52.4 MB"
-
-// Subscribe to progress updates
-upload.subscribe((state) => {
-  console.log(`${state.percent}% - ${state.status}`);
-});
-
-// 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-Upload-Id": uploadId,
-        "X-Chunk-Index": String(index),
-      },
-      body: data,
-    });
-  },
-});
+const committed = await fg.uploads.sessions.commit({ sessionId: session.id });
+console.log(committed.node.id);
 ```
 
-## API Endpoints
-
-All `/files/*` endpoints require `Authorization: Bearer <token>`.
-
-| 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. Use `?computeSizes=true` for recursive dir sizes |
-| GET | `/files/content` | Download file or directory (TAR). Use `?inline=true` to view in browser |
-| PUT | `/files/content` | Upload file |
-| POST | `/files/mkdir` | Create directory |
-| DELETE | `/files/delete` | Delete file or directory |
-| POST | `/files/transfer` | Move or copy file/directory. Cross-base copy requires ownership |
-| GET | `/files/search` | Search with glob pattern. Use `?directories=true` to include folders |
-| POST | `/files/upload/start` | Start or resume chunked upload |
-| POST | `/files/upload/chunk` | Upload a chunk |
-| GET | `/files/thumbnail/image` | Generate image thumbnail on-the-fly |
+Segment PUTs are idempotent when the content matches. Commit is explicit and
+safe to retry after success.
 
-## Security
+## Utilities
 
-Filegate implements multiple security layers:
-
-- **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.
-
-## Development
-
-```bash
-# Install dependencies
-bun install
+Pure helpers live under `@valentinkolb/filegate/utils` and do not require a
+Filegate token:
 
-# Run server
-FILE_PROXY_TOKEN=dev ALLOWED_BASE_PATHS=/tmp bun run src/index.ts
+```ts
+import { uploads } from "@valentinkolb/filegate/utils";
 
-# Run tests
-bun run test:unit
-bun run test:integration:run
+const checksum = await uploads.checksum.sha256(file);
 ```
 
-## License
+## Documentation
 
-MIT
+- Project README: https://github.com/ValentinKolb/filegate#readme
+- TypeScript guide: https://github.com/ValentinKolb/filegate/blob/main/docs/ts-client.md
+- HTTP routes: https://github.com/ValentinKolb/filegate/blob/main/docs/http-routes.md