@rebasepro/cli 0.5.0 → 0.6.1

package/skills/rebase-storage/SKILL.md

@@ -0,0 +1,765 @@
+---
+name: rebase-storage
+description: Guide for setting up and using file storage in Rebase. Use this skill when the user needs to configure S3 or local file storage, handle file uploads, TUS resumable uploads, image transformations, or integrate the media manager.
+---
+
+# Rebase Storage
+
+Rebase provides built-in file storage with support for local filesystem and S3-compatible services, TUS v1.0.0 resumable uploads, on-the-fly image transformation, and a multi-backend registry.
+
+> **IMPORTANT FOR AGENTS:** Always read the `rebase-basics` skill first before using this skill. Storage requires a running Rebase backend with `initializeRebaseBackend()`.
+
+## Storage Configuration
+
+The `storage` option in `initializeRebaseBackend()` accepts three forms:
+
+| Form | Type | Description |
+|------|------|-------------|
+| Single config | `BackendStorageConfig` | `{ type: 'local' | 's3', ... }` — creates a single `(default)` backend |
+| Single controller | `StorageController` | A custom controller instance — registered as `(default)` |
+| Multi-backend map | `Record<string, BackendStorageConfig \| StorageController>` | Named backends, first becomes `(default)` if no `(default)` key |
+
+### LocalStorageConfig
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `"local"` | — | **Required.** Must be `"local"` |
+| `basePath` | `string` | — | **Required.** Base directory for file storage (e.g., `"./uploads"`) |
+| `maxFileSize` | `number` | `52428800` (50 MB) | Maximum file size in bytes |
+| `allowedMimeTypes` | `string[]` | `undefined` (all allowed) | Restrict uploads to these MIME types |
+| `baseUrl` | `string` | Auto-detected | Base URL for generating download URLs |
+
+### S3StorageConfig
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `"s3"` | — | **Required.** Must be `"s3"` |
+| `bucket` | `string` | — | **Required.** S3 bucket name |
+| `accessKeyId` | `string` | — | **Required.** AWS access key ID |
+| `secretAccessKey` | `string` | — | **Required.** AWS secret access key |
+| `region` | `string` | `"us-east-1"` | AWS region |
+| `endpoint` | `string` | `undefined` | Custom endpoint URL (required for MinIO, R2, Hetzner, etc.) |
+| `forcePathStyle` | `boolean` | Auto-enabled when `endpoint` is set | Use path-style URLs (required for MinIO) |
+| `maxFileSize` | `number` | `52428800` (50 MB) | Maximum file size in bytes |
+| `allowedMimeTypes` | `string[]` | `undefined` (all allowed) | Restrict uploads to these MIME types |
+| `signedUrlExpiration` | `number` | `3600` | Signed URL expiry in seconds |
+
+### StorageRoutesConfig
+
+These options are set internally when mounting routes but are derived from the backend config:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `controller` | `StorageController` | — | **Required.** The storage controller instance |
+| `basePath` | `string` | `"/api/storage"` | Base path for storage routes |
+| `requireAuth` | `boolean` | `true` | Require authentication for write operations |
+| `publicRead` | `boolean` | `false` | Allow unauthenticated read access to stored files |
+
+## Storage Providers
+
+### Local Storage
+
+Store files on the local filesystem. Best for development and simple single-server deployments.
+
+```typescript
+import { initializeRebaseBackend } from "@rebasepro/server-core";
+
+const backend = await initializeRebaseBackend({
+    server, app,
+    bootstrappers: [/* ... */],
+    storage: {
+        type: "local",
+        basePath: "./uploads",
+        maxFileSize: 50 * 1024 * 1024, // 50MB (default)
+        allowedMimeTypes: ["image/jpeg", "image/png", "application/pdf"],
+        baseUrl: "http://localhost:3001/api/storage",
+    },
+});
+```
+
+> **WARNING FOR AGENTS:** In production, the backend logs a warning if local storage is used. Local files are lost on container restart. Set `FORCE_LOCAL_STORAGE=true` to suppress the warning, or use S3 for production.
+
+Local storage uses a `{basePath}/{bucket}/{path}` directory structure. The default bucket is `"default"`. Every uploaded file gets a sidecar `.metadata.json` file containing:
+
+```json
+{
+  "contentType": "image/jpeg",
+  "size": 204800,
+  "uploadedAt": "2026-01-15T10:30:00.000Z"
+}
+```
+
+Local storage includes **path traversal protection** — any resolved path that escapes the bucket directory throws an error.
+
+### S3-Compatible Storage
+
+Works with AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2, Hetzner Object Storage, Backblaze B2, and any S3-compatible service. GCS also works via its S3-compatible interoperability API.
+
+```typescript
+const backend = await initializeRebaseBackend({
+    server, app,
+    bootstrappers: [/* ... */],
+    storage: {
+        type: "s3",
+        bucket: process.env.S3_BUCKET!,
+        region: process.env.S3_REGION,
+        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+        endpoint: process.env.S3_ENDPOINT,       // For MinIO, R2, etc.
+        forcePathStyle: true,                     // Required for MinIO
+        signedUrlExpiration: 3600,                // URL expiry in seconds
+    },
+});
+```
+
+The S3 controller:
+- Auto-enables `forcePathStyle` when a custom `endpoint` is set
+- Maps the logical bucket name `"default"` to the configured S3 bucket
+- Supports `s3://` and `gs://` URL schemes in key parameters for backward compatibility
+- Flattens nested metadata to string values (S3 requirement)
+
+### Multiple Storage Backends
+
+Rebase supports multiple storage backends simultaneously via the `StorageRegistry`:
+
+```typescript
+const backend = await initializeRebaseBackend({
+    server, app,
+    bootstrappers: [/* ... */],
+    storage: {
+        "(default)": { type: "local", basePath: "./uploads" },
+        "media": {
+            type: "s3",
+            bucket: "my-media-bucket",
+            accessKeyId: "...",
+            secretAccessKey: "...",
+        },
+    },
+});
+```
+
+> **IMPORTANT FOR AGENTS:** If no `"(default)"` key is provided, the first entry is automatically registered as the default (with a console warning). The REST API routes always use the default controller. Use `storageRegistry.get("media")` or `storageRegistry.getOrDefault("media")` to access named backends programmatically.
+
+### StorageRegistry API
+
+The `StorageRegistry` interface:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `register` | `(id: string, controller: StorageController) => void` | Register a controller with an ID |
+| `getDefault` | `() => StorageController` | Get the `(default)` controller (throws if none) |
+| `get` | `(id: string \| undefined \| null) => StorageController \| undefined` | Get by ID, returns `undefined` if not found |
+| `getOrDefault` | `(id: string \| undefined \| null) => StorageController` | Get by ID with fallback to default (throws if neither exists) |
+| `has` | `(id: string) => boolean` | Check if a storage ID exists |
+| `list` | `() => string[]` | List all registered storage IDs |
+| `size` | `() => number` | Number of registered controllers |
+
+### Custom Storage Providers
+
+Implement the `StorageController` interface for unsupported providers (Azure Blob, native GCS SDK, etc.):
+
+```typescript
+interface StorageController {
+    putObject(props: UploadFileProps): Promise<UploadFileResult>;
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+    getObject(key: string, bucket?: string): Promise<File | null>;
+    deleteObject(key: string, bucket?: string): Promise<void>;
+    listObjects(prefix: string, options?: {
+        bucket?: string;
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<StorageListResult>;
+    getType(): string;  // e.g. "gcs", "azure"
+}
+```
+
+Pass the instance directly to `storage`:
+
+```typescript
+storage: new MyGCSStorageController({ projectId: "...", bucket: "..." }),
+```
+
+## Environment Variables
+
+The backend validates storage-related environment variables via a Zod schema:
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `STORAGE_TYPE` | `"local" \| "s3"` | `"local"` | Storage provider type |
+| `STORAGE_PATH` | `string` | `"./uploads"` | Base path for local storage / TUS temp directory |
+| `FORCE_LOCAL_STORAGE` | `"true" \| "false"` | `false` | Suppress the production warning for local storage |
+| `S3_BUCKET` | `string` | — | S3 bucket name |
+| `S3_REGION` | `string` | — | S3 region |
+| `S3_ACCESS_KEY_ID` | `string` | — | S3 access key ID |
+| `S3_SECRET_ACCESS_KEY` | `string` | — | S3 secret access key |
+| `S3_ENDPOINT` | `string` (URL) | — | Custom S3-compatible endpoint |
+| `S3_FORCE_PATH_STYLE` | `"true" \| "false"` | — | Enable path-style URLs |
+
+```env
+STORAGE_TYPE=s3
+S3_BUCKET=my-bucket
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=AKIA...
+S3_SECRET_ACCESS_KEY=...
+S3_ENDPOINT=https://minio.example.com    # Optional: for MinIO, R2, etc.
+S3_FORCE_PATH_STYLE=true                 # Optional: for MinIO
+```
+
+## REST API Endpoints
+
+All storage routes are mounted at `/api/storage` by default. Write operations require authentication when `requireAuth` is `true` (the default). Read operations also require authentication unless `publicRead` is `true`.
+
+### Standard Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `POST` | `/api/storage/upload` | Write | Upload a file (multipart/form-data) |
+| `GET` | `/api/storage/file/*` | Read | Download / serve a file (supports image transforms) |
+| `DELETE` | `/api/storage/file/*` | Write | Delete a file |
+| `GET` | `/api/storage/metadata/*` | Read | Get file metadata |
+| `GET` | `/api/storage/list` | Write | List files in a prefix |
+| `POST` | `/api/storage/folder` | Write | Create a new folder |
+
+### TUS Resumable Upload Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| `OPTIONS` | `/api/storage/tus` | None | TUS capability discovery |
+| `POST` | `/api/storage/tus` | Write | Create a new resumable upload |
+| `HEAD` | `/api/storage/tus/:id` | Read | Query upload progress |
+| `PATCH` | `/api/storage/tus/:id` | Write | Append data to an upload |
+| `DELETE` | `/api/storage/tus/:id` | Write | Cancel and remove an upload |
+
+### POST /api/storage/upload
+
+Upload a file via `multipart/form-data`.
+
+**Request body fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | `File` | Yes | The file to upload |
+| `key` | `string` | No | Storage key/path. Falls back to original filename, then `"unnamed"` |
+| `bucket` | `string` | No | Target bucket name |
+| `metadata_*` | `string` | No | Custom metadata keys prefixed with `metadata_` |
+
+**Response** (201):
+
+```json
+{
+  "success": true,
+  "data": {
+    "key": "products/images/photo.jpg",
+    "bucket": "default",
+    "storageUrl": "local://default/products/images/photo.jpg"
+  }
+}
+```
+
+The `storageUrl` format is `local://{bucket}/{key}` for local storage and `s3://{bucket}/{key}` for S3.
+
+**Error responses:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | No file provided in request body |
+| 413 | File exceeds `maxFileSize` (body limit middleware) |
+
+### GET /api/storage/file/{path}
+
+Download or serve a file. The path can include a bucket prefix (e.g., `/file/default/images/photo.jpg`) or omit it to use the default bucket.
+
+For **local storage**, files are served directly from disk with content type read from the `.metadata.json` sidecar file.
+
+For **S3 storage**, files are proxied through the backend (not redirected to signed URLs). This avoids mixed-content issues and unreachable internal VPC endpoints.
+
+**Image transformation query parameters** can be appended — see [Image Transformation](#image-transformation).
+
+**Response headers:**
+- `Content-Type` — from metadata or inferred
+- `Cache-Control: public, max-age=31536000, immutable` (when image transforms are applied)
+- `Cache-Control: public, max-age=3600, immutable` (for S3-proxied files without transforms)
+
+### GET /api/storage/metadata/{path}
+
+Get metadata for a file without downloading it.
+
+**Response** (200):
+
+```json
+{
+  "success": true,
+  "data": {
+    "bucket": "default",
+    "fullPath": "products/images/photo.jpg",
+    "name": "photo.jpg",
+    "size": 204800,
+    "contentType": "image/jpeg",
+    "customMetadata": {}
+  }
+}
+```
+
+### GET /api/storage/list
+
+List files and folders in a given prefix.
+
+**Query parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prefix` | `string` | `""` | Path prefix to list (also accepts `path` for backward compat) |
+| `bucket` | `string` | `"default"` (local) | Bucket name |
+| `maxResults` | `number` | `1000` | Maximum number of results |
+| `pageToken` | `string` | — | Pagination token from previous response |
+
+**Response** (200):
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      { "bucket": "default", "fullPath": "images/photo.jpg", "name": "photo.jpg" }
+    ],
+    "prefixes": [
+      { "bucket": "default", "fullPath": "images/thumbnails", "name": "thumbnails" }
+    ],
+    "nextPageToken": "25"
+  }
+}
+```
+
+- `items` — files in the prefix
+- `prefixes` — subdirectories/folders in the prefix
+- `nextPageToken` — pass to the next request for pagination (only present if more results exist)
+
+For S3, listing uses the `Delimiter: "/"` for folder-like behavior via `ListObjectsV2Command`.
+
+### POST /api/storage/folder
+
+Create a new folder.
+
+**Request body:**
+
+```json
+{
+  "path": "products/images/thumbnails",
+  "bucket": "default"
+}
+```
+
+For **local storage**, creates the directory on disk. For **S3**, creates a zero-byte marker object with a trailing `/` and content type `application/x-directory`.
+
+**Response** (201):
+
+```json
+{ "success": true, "message": "Folder created" }
+```
+
+### DELETE /api/storage/file/{path}
+
+Delete a file. For local storage, also deletes the `.metadata.json` sidecar file. Directories can only be deleted if empty (ENOTEMPTY errors are silently ignored).
+
+**Response** (200):
+
+```json
+{ "success": true, "message": "File deleted" }
+```
+
+## TUS Resumable Uploads
+
+Rebase implements [TUS v1.0.0](https://tus.io/protocols/resumable-upload) with the **Creation** and **Termination** extensions. This allows reliable upload of large files (up to 5 GB) with automatic resume on network failure.
+
+### TUS Configuration
+
+| Setting | Value |
+|---------|-------|
+| TUS version | `1.0.0` |
+| Extensions | `creation`, `termination` |
+| Max upload size | 5 GB (`5 * 1024 * 1024 * 1024` bytes) |
+| Stale upload expiry | 24 hours |
+| Cleanup interval | Every 60 seconds |
+| Temp directory | `{storageBasePath}/.tus-uploads` |
+
+TUS uploads are stored in a temporary directory and automatically moved to the final storage backend (via `putObject`) when the upload completes.
+
+### TUS Protocol Flow
+
+```
+1. OPTIONS /api/storage/tus          → Discover capabilities
+2. POST    /api/storage/tus          → Create upload, get Location header
+3. PATCH   /api/storage/tus/:id      → Send chunks (repeat until done)
+4. (auto)  Upload finalized → moved to storage controller
+```
+
+### OPTIONS /api/storage/tus
+
+Returns TUS server capabilities.
+
+**Response headers:**
+
+```
+Tus-Resumable: 1.0.0
+Tus-Version: 1.0.0
+Tus-Extension: creation,termination
+Tus-Max-Size: 5368709120
+```
+
+### POST /api/storage/tus (Create)
+
+Create a new resumable upload.
+
+**Required request headers:**
+
+| Header | Description |
+|--------|-------------|
+| `Upload-Length` | Total file size in bytes (must be > 0 and ≤ 5 GB) |
+| `Upload-Metadata` | TUS metadata as `key base64value,key2 base64value2` |
+
+**Supported metadata keys:**
+
+| Key | Description |
+|-----|-------------|
+| `filename` | Original file name (used as storage key if no `key` provided) |
+| `key` | Explicit storage key/path |
+| `bucket` | Target bucket |
+| `contentType` | File MIME type |
+| `filetype` | Alternative MIME type key (fallback) |
+
+**Response** (201):
+
+```
+Location: http://localhost:3001/api/storage/tus/550e8400-e29b-41d4-a716-446655440000
+Tus-Resumable: 1.0.0
+Upload-Offset: 0
+```
+
+### HEAD /api/storage/tus/:id (Progress)
+
+Query the current upload progress.
+
+**Response** (200):
+
+```
+Tus-Resumable: 1.0.0
+Upload-Offset: 1048576
+Upload-Length: 10485760
+Cache-Control: no-store
+```
+
+### PATCH /api/storage/tus/:id (Append)
+
+Append data to an in-progress upload.
+
+**Required request headers:**
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `application/offset+octet-stream` |
+| `Upload-Offset` | Must match the server's current offset |
+
+**Error responses:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Missing `Upload-Offset` header, or upload already completed |
+| 409 | Offset mismatch (client offset ≠ server offset) |
+| 413 | Chunk would exceed declared `Upload-Length` |
+| 415 | Wrong `Content-Type` (must be `application/offset+octet-stream`) |
+
+When `Upload-Offset` reaches `Upload-Length`, the upload is **automatically finalized**: the temp file is read, a `File` object is created with the metadata-derived MIME type, `putObject` is called on the storage controller, and the temp file is cleaned up.
+
+### DELETE /api/storage/tus/:id (Terminate)
+
+Cancel and remove an in-progress upload. Deletes the temp file and removes the upload from the in-memory registry.
+
+### TUS Client Example
+
+```typescript
+// Using tus-js-client (npm install tus-js-client)
+import * as tus from "tus-js-client";
+
+const file = document.querySelector<HTMLInputElement>("#fileInput")!.files![0];
+
+const upload = new tus.Upload(file, {
+    endpoint: "http://localhost:3001/api/storage/tus",
+    retryDelays: [0, 1000, 3000, 5000],
+    metadata: {
+        filename: file.name,
+        filetype: file.type,
+        key: `uploads/${file.name}`,
+        bucket: "default",
+    },
+    headers: {
+        Authorization: `Bearer ${accessToken}`,
+    },
+    onError: (error) => console.error("Upload failed:", error),
+    onProgress: (bytesUploaded, bytesTotal) => {
+        const pct = ((bytesUploaded / bytesTotal) * 100).toFixed(1);
+        console.log(`${pct}%`);
+    },
+    onSuccess: () => console.log("Upload complete:", upload.url),
+});
+
+upload.start();
+```
+
+## Image Transformation
+
+Rebase provides on-the-fly image resize, crop, format conversion, and quality adjustment. Transformations are applied by adding query parameters to the `GET /api/storage/file/*` endpoint.
+
+> **IMPORTANT FOR AGENTS:** Image transformation requires the `sharp` npm package as an **optional peer dependency**. Install it: `pnpm add sharp`. If `sharp` is not installed, requesting a transform will throw an error.
+
+### Transform Query Parameters
+
+| Parameter | Type | Range | Default | Description |
+|-----------|------|-------|---------|-------------|
+| `width` | `number` | 1–4096 | — | Target width in pixels |
+| `height` | `number` | 1–4096 | — | Target height in pixels |
+| `quality` | `number` | 1–100 | `80` | Output quality |
+| `format` | `string` | `webp`, `avif`, `jpeg`, `png` | `webp` | Output format |
+| `fit` | `string` | `cover`, `contain`, `fill`, `inside`, `outside` | `cover` | Resize fit mode |
+
+All dimensions are capped at **4096 px** to prevent abuse. `withoutEnlargement` is enabled — images are never upscaled.
+
+### Transform Examples
+
+```
+# Resize to 300px wide, auto height, WebP format
+GET /api/storage/file/default/images/photo.jpg?width=300
+
+# Resize to 800x600, JPEG at 90% quality
+GET /api/storage/file/default/images/photo.jpg?width=800&height=600&format=jpeg&quality=90
+
+# Convert to AVIF with contain fit
+GET /api/storage/file/default/images/photo.jpg?format=avif&fit=contain&width=500&height=500
+```
+
+### Transformable Image Types
+
+Only raster images are transformable. SVG and GIF are **excluded**:
+
+```
+✅  image/jpeg, image/png, image/webp, image/bmp, image/tiff
+❌  image/svg+xml, image/gif
+```
+
+### Transform Cache
+
+Transformed images are cached in an **LRU in-memory cache** to avoid redundant processing:
+
+| Setting | Value |
+|---------|-------|
+| Max entries | 500 |
+| TTL | 1 hour (3,600,000 ms) |
+| Cache key | `{filePath}::{JSON.stringify(options)}` |
+| Eviction policy | LRU (oldest entry evicted when at capacity) |
+
+Transformed responses include `Cache-Control: public, max-age=31536000, immutable`.
+
+## Client SDK Methods
+
+The `@rebasepro/client` package provides a `StorageSource` interface via `createStorage(transport)`. These methods are available on `client.storage` (or through the React/Studio hooks).
+
+### putObject
+
+Upload a file.
+
+```typescript
+const result = await client.storage.putObject({
+    file: myFile,                              // File object
+    key: "products/images/photo.jpg",          // Storage key/path
+    bucket: "default",                         // Optional bucket
+    metadata: { category: "product" },         // Optional custom metadata
+});
+// result: { key: "products/images/photo.jpg", bucket: "default", storageUrl: "local://..." }
+```
+
+The SDK sends a `multipart/form-data` request to `POST /api/storage/upload`. Custom metadata keys are prefixed with `metadata_` in the form data.
+
+### getSignedUrl
+
+Get a download URL and metadata for a file. Results are cached in-memory on the client.
+
+```typescript
+const config = await client.storage.getSignedUrl(
+    "products/images/photo.jpg",   // key or storageUrl (local:// or s3://)
+    "default"                       // optional bucket
+);
+
+if (config.fileNotFound) {
+    console.log("File does not exist");
+} else {
+    console.log(config.url);       // Full URL with auth token appended
+    console.log(config.metadata);  // { bucket, fullPath, name, size, contentType, customMetadata }
+}
+```
+
+The URL is constructed as `{baseUrl}/api/storage/file/{path}?token={accessToken}`.
+
+Protocol prefixes (`local://`, `s3://`) are automatically stripped from the key.
+
+### getObject
+
+Download a file as a `File` object.
+
+```typescript
+const file = await client.storage.getObject(
+    "products/images/photo.jpg",   // key or storageUrl
+    "default"                       // optional bucket
+);
+
+if (file) {
+    console.log(file.name);  // "photo.jpg"
+    console.log(file.type);  // "image/jpeg"
+    const blob = new Blob([file]);
+    // use blob for display, further processing, etc.
+}
+```
+
+> **IMPORTANT FOR AGENTS:** `getObject` uses raw `fetch` (not the JSON transport) because the response is a binary blob, not JSON.
+
+### deleteObject
+
+Delete a file. Silently ignores 404 errors (file already deleted).
+
+```typescript
+await client.storage.deleteObject(
+    "products/images/photo.jpg",   // key or storageUrl
+    "default"                       // optional bucket
+);
+```
+
+### listObjects
+
+List files and folders in a prefix with pagination.
+
+```typescript
+const result = await client.storage.listObjects("products/images", {
+    bucket: "default",
+    maxResults: 50,
+    pageToken: undefined,  // from previous result.nextPageToken
+});
+
+console.log(result.items);       // files: StorageReference[]
+console.log(result.prefixes);    // folders: StorageReference[]
+console.log(result.nextPageToken); // for next page, or undefined
+```
+
+## Collection File Upload Properties
+
+Define file upload fields in your collections using the `storage` option on string properties:
+
+```typescript
+import { PostgresCollection } from "@rebasepro/types";
+
+const productsCollection: PostgresCollection = {
+    name: "Products",
+    table: "products",
+    properties: {
+        image: {
+            name: "Product Image",
+            type: "string",
+            storage: {
+                storagePath: "products/images",
+                acceptedFiles: ["image/*"],
+                maxSize: 5 * 1024 * 1024, // 5MB
+            }
+        },
+        documents: {
+            name: "Documents",
+            type: "array",
+            of: {
+                type: "string",
+                storage: {
+                    storagePath: "products/documents",
+                    acceptedFiles: ["application/pdf", "application/msword"],
+                }
+            }
+        }
+    }
+};
+```
+
+## Storage Browser (Studio)
+
+The `@rebasepro/studio` package includes a built-in `StorageView` component:
+- Browse uploaded files and folders with a tree sidebar
+- Drag-and-drop file uploads
+- Image, video, and audio previews with metadata
+- File search and filtering
+- Grid and list view modes
+
+## Validation and Error Handling
+
+### File Size Validation
+
+File size is validated at two levels:
+
+1. **Hono body limit middleware** — returns `413` with `PAYLOAD_TOO_LARGE` before the file reaches the controller. The limit is derived from `maxFileSize` in the storage config (default 50 MB).
+2. **Controller-level validation** — the controller's `validateFile()` checks `file.size` against `maxFileSize` and throws an `Error` if exceeded.
+
+### MIME Type Validation
+
+When `allowedMimeTypes` is set in the storage config, uploads with disallowed MIME types are rejected with an error:
+
+```
+File type application/zip is not allowed. Allowed types: image/jpeg, image/png
+```
+
+### Common MIME Type Constants
+
+The storage module exports two convenience arrays:
+
+```typescript
+import { IMAGE_MIME_TYPES, DOCUMENT_MIME_TYPES } from "@rebasepro/server-core";
+
+// IMAGE_MIME_TYPES:
+// ["image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml", "image/bmp", "image/tiff"]
+
+// DOCUMENT_MIME_TYPES:
+// ["application/pdf", "application/msword",
+//  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+//  "application/vnd.ms-excel",
+//  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+//  "application/vnd.ms-powerpoint",
+//  "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+//  "text/plain", "text/csv"]
+```
+
+### TUS Error Codes
+
+| HTTP Status | Condition |
+|-------------|-----------|
+| 400 | Missing/invalid `Upload-Length` header, missing `Upload-Offset`, upload already completed |
+| 404 | Upload ID not found |
+| 409 | `Upload-Offset` mismatch (client offset ≠ server offset) |
+| 413 | `Upload-Length` exceeds 5 GB max, or chunk exceeds declared length |
+| 415 | `Content-Type` is not `application/offset+octet-stream` |
+
+## Metadata Sidecar Files (Local Storage)
+
+For local storage, every uploaded file has a companion `.metadata.json` file saved alongside it. This sidecar file stores:
+
+```json
+{
+  "contentType": "image/jpeg",
+  "size": 204800,
+  "uploadedAt": "2026-01-15T10:30:00.000Z",
+  "category": "product"
+}
+```
+
+- `contentType` and `size` are always present
+- Custom metadata from the upload request is merged in
+- The content type from this file is used when serving files via `GET /file/*`
+- When a file is deleted, its `.metadata.json` is also deleted
+- Metadata files are skipped when listing directory contents (filtered out by name pattern)
+
+## References
+
+- **Documentation:** [rebase.pro/docs](https://rebase.pro/docs)
+- **GitHub:** [github.com/rebasepro/rebase](https://github.com/rebasepro/rebase)
+- **TUS Protocol:** [tus.io/protocols/resumable-upload](https://tus.io/protocols/resumable-upload)
+- **Sharp (image transforms):** [sharp.pixelplumbing.com](https://sharp.pixelplumbing.com)