@od-oneapp/storage 2026.1.1301

package/README.md

@@ -0,0 +1,854 @@
+# @repo/storage
+
+**Production-grade, multi-provider storage abstraction layer** for Next.js applications with full TypeScript support.
+
+[![Type Safety](https://img.shields.io/badge/TypeScript-Strict-blue)](./tsconfig.json)
+[![Test Coverage](https://img.shields.io/badge/Tests-38_files-green)](#testing)
+[![Edge Compatible](https://img.shields.io/badge/Edge-Compatible-purple)](#edge-runtime-support)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage Patterns](#usage-patterns)
+- [Provider Configuration](#provider-configuration)
+- [Security Best Practices](#security-best-practices)
+- [API Reference](#api-reference)
+- [Migration Guide](#migration-guide)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+
+---
+
+## Overview
+
+The `@repo/storage` package provides a unified interface for cloud storage operations across multiple providers:
+
+- **Vercel Blob**: Optimized for Vercel deployments with edge support
+- **Cloudflare R2**: S3-compatible object storage with global distribution
+- **Cloudflare Images**: Specialized image optimization and delivery
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│           Application Code                       │
+├─────────────────────────────────────────────────┤
+│   @repo/storage (Unified Interface)             │
+├──────────────┬──────────────┬───────────────────┤
+│ Vercel Blob  │ Cloudflare R2│ Cloudflare Images │
+├──────────────┴──────────────┴───────────────────┤
+│         Cloud Storage Providers                  │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Features
+
+### Core Capabilities
+
+✅ **Multi-Provider Support**: Switch between providers with configuration change ✅ **Type-Safe**: Full TypeScript with
+strict mode enabled ✅ **Edge Compatible**: Works in Vercel Edge Runtime and Cloudflare Workers ✅ **Server Actions**:
+24+ Next.js server actions for App Router ✅ **Multipart Uploads**: Automatic chunking for large files (>100MB) ✅
+**Progress Tracking**: Real-time upload progress with callbacks ✅ **Abort Support**: Cancel in-progress uploads ✅
+**Retry Logic**: Automatic retry with exponential backoff ✅ **Health Checks**: Monitor provider availability ✅
+**Structured Errors**: Comprehensive error types with context
+
+### Security Features
+
+🔒 **Authentication**: Built-in auth helpers with session management 🔒 **Rate Limiting**: Configurable rate limits per
+operation 🔒 **Input Validation**: File size, MIME type, and path validation 🔒 **CSRF Protection**: Origin checking and
+token validation 🔒 **Path Sanitization**: Prevent directory traversal attacks
+
+### Developer Experience
+
+🎯 **Comprehensive Tests**: 38 test files with extensive coverage 🎯 **Detailed Examples**: Real-world usage patterns in
+`/examples` 🎯 **JSDoc Documentation**: Inline documentation for all public APIs 🎯 **Error Messages**: Clear,
+actionable error messages 🎯 **TypeScript First**: Designed for TypeScript with excellent type inference
+
+---
+
+## Installation
+
+This is an internal workspace package. Add it to your package dependencies:
+
+```json
+{
+  "dependencies": {
+    "@repo/storage": "workspace:*"
+  }
+}
+```
+
+Then install:
+
+```bash
+pnpm install
+```
+
+---
+
+## Quick Start
+
+### 1. Configure Environment Variables
+
+Create a `.env` file:
+
+```bash
+# Required: Choose your provider
+STORAGE_PROVIDER=vercel-blob # or cloudflare-r2, cloudflare-images, multi
+
+# Vercel Blob configuration
+VERCEL_BLOB_READ_WRITE_TOKEN=vercel_blob_rw_xxxxx
+
+# Cloudflare R2 configuration
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET=my-bucket
+
+# Cloudflare Images configuration
+CLOUDFLARE_IMAGES_ACCOUNT_ID=your-account-id
+CLOUDFLARE_IMAGES_API_TOKEN=your-api-token
+
+# Security settings (recommended for production)
+STORAGE_ENFORCE_AUTH=true
+STORAGE_ENABLE_RATE_LIMIT=true
+STORAGE_ENFORCE_CSRF=true
+
+# File limits
+STORAGE_MAX_FILE_SIZE=104857600 # 100MB
+STORAGE_MAX_FILES_PER_UPLOAD=10
+
+# Rate limiting
+STORAGE_RATE_LIMIT_REQUESTS=100
+STORAGE_RATE_LIMIT_WINDOW_MS=60000 # 1 minute
+```
+
+### 2. Basic Upload (Client-Side)
+
+```typescript
+'use client';
+
+import { upload } from '@repo/storage/client';
+import { useState } from 'react';
+
+export function FileUploader() {
+  const [uploading, setUploading] = useState(false);
+
+  async function handleUpload(file: File) {
+    setUploading(true);
+    try {
+      const blob = await upload(file.name, file, {
+        access: 'public',
+        handleUploadUrl: '/api/upload',
+      });
+      console.log('Uploaded:', blob.url);
+    } catch (error) {
+      console.error('Upload failed:', error);
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  return (
+    <input
+      type="file"
+      onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])}
+      disabled={uploading}
+    />
+  );
+}
+```
+
+### 3. Basic Upload (Server-Side)
+
+```typescript
+"use server";
+
+import { uploadMediaAction } from "@repo/storage/server/next";
+
+export async function uploadFile(file: File) {
+  const result = await uploadMediaAction(`uploads/${Date.now()}-${file.name}`, file, {
+    contentType: file.type,
+    maxFileSize: 10 * 1024 * 1024, // 10MB
+    allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"]
+  });
+
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+
+  return result.data;
+}
+```
+
+### 4. List Files
+
+```typescript
+import { storage } from "@repo/storage/server";
+
+export async function listFiles(prefix: string) {
+  const files = await storage.list({
+    prefix,
+    limit: 100
+  });
+
+  return files.map((file) => ({
+    key: file.key,
+    url: file.url,
+    size: file.size,
+    lastModified: file.lastModified
+  }));
+}
+```
+
+---
+
+## Usage Patterns
+
+### Client-Side Upload with Progress
+
+```typescript
+'use client';
+
+import { upload } from '@repo/storage/client/next';
+import { useState } from 'react';
+
+export function ProgressUploader() {
+  const [progress, setProgress] = useState(0);
+
+  async function handleUpload(file: File) {
+    const blob = await upload(file.name, file, {
+      access: 'public',
+      handleUploadUrl: '/api/upload',
+      onUploadProgress: ({ percentage }) => {
+        setProgress(percentage ?? 0);
+      },
+    });
+
+    return blob;
+  }
+
+  return (
+    <div>
+      <input type="file" onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])} />
+      {progress > 0 && <progress value={progress} max={100} />}
+    </div>
+  );
+}
+```
+
+### Multiple File Upload
+
+```typescript
+"use client";
+
+import { uploadMultipleFiles } from "@repo/storage/client/next";
+
+export async function uploadFiles(files: File[]) {
+  const results = await uploadMultipleFiles(
+    files.map((file) => ({
+      file,
+      key: `uploads/${Date.now()}-${file.name}`
+    })),
+    {
+      onProgress: (key, progress) => {
+        console.log(`${key}: ${progress.percentage}%`);
+      },
+      onError: (key, error) => {
+        console.error(`${key} failed:`, error);
+      }
+    }
+  );
+
+  return results;
+}
+```
+
+### Multipart Upload (Large Files)
+
+```typescript
+import { createMultipartUploadManager } from "@repo/storage/server";
+import { storage } from "@repo/storage/server";
+
+export async function uploadLargeFile(file: File) {
+  const manager = createMultipartUploadManager(storage, `large-files/${file.name}`, file, {
+    partSize: 10 * 1024 * 1024, // 10MB parts
+    queueSize: 8, // 8 concurrent uploads
+    onProgress: (progress) => {
+      console.log(`Progress: ${progress.percentage}%`);
+    }
+  });
+
+  const result = await manager.upload();
+  return result;
+}
+```
+
+### Presigned URLs (Direct Upload)
+
+```typescript
+import { storage } from "@repo/storage/server";
+
+export async function getUploadUrl(filename: string) {
+  const presigned = await storage.getPresignedUploadUrl(`uploads/${filename}`, {
+    expiresIn: 3600, // 1 hour
+    contentType: "image/jpeg"
+  });
+
+  return presigned;
+}
+
+// Client-side: Upload directly to presigned URL
+async function uploadWithPresignedUrl(file: File, presigned: PresignedUploadUrl) {
+  const formData = new FormData();
+  Object.entries(presigned.fields).forEach(([key, value]) => {
+    formData.append(key, value);
+  });
+  formData.append("file", file);
+
+  const response = await fetch(presigned.url, {
+    method: "POST",
+    body: formData
+  });
+
+  return response.ok;
+}
+```
+
+### Delete Files
+
+```typescript
+import { deleteMediaAction } from "@repo/storage/server/next";
+
+export async function deleteFile(key: string) {
+  const result = await deleteMediaAction(key);
+
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+}
+```
+
+### Bulk Operations
+
+```typescript
+import { bulkDeleteMediaAction } from "@repo/storage/server/next";
+
+export async function deleteMultipleFiles(keys: string[]) {
+  const result = await bulkDeleteMediaAction(keys);
+
+  console.log("Succeeded:", result.data?.succeeded);
+  console.log("Failed:", result.data?.failed);
+
+  return result;
+}
+```
+
+---
+
+## Provider Configuration
+
+### Vercel Blob
+
+**Best for**: Vercel deployments, edge runtime, simple use cases
+
+```bash
+STORAGE_PROVIDER=vercel-blob
+VERCEL_BLOB_READ_WRITE_TOKEN=vercel_blob_rw_xxxxx
+```
+
+**Features**:
+
+- ✅ Edge compatible
+- ✅ Automatic CDN distribution
+- ✅ Multipart uploads
+- ✅ Progress tracking
+- ❌ No presigned URLs
+
+### Cloudflare R2
+
+**Best for**: Large file storage, S3 compatibility, cost optimization
+
+```bash
+STORAGE_PROVIDER=cloudflare-r2
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET=my-bucket
+```
+
+**Features**:
+
+- ✅ S3-compatible API
+- ✅ Presigned URLs
+- ✅ Multipart uploads
+- ✅ Custom domains
+- ❌ Not edge compatible (uses Node.js AWS SDK)
+
+### Cloudflare Images
+
+**Best for**: Image optimization, automatic format conversion, variants
+
+```bash
+STORAGE_PROVIDER=cloudflare-images
+CLOUDFLARE_IMAGES_ACCOUNT_ID=your-account-id
+CLOUDFLARE_IMAGES_API_TOKEN=your-api-token
+CLOUDFLARE_IMAGES_SIGNING_KEY=your-signing-key               # Optional
+CLOUDFLARE_IMAGES_DELIVERY_URL=https://imagedelivery.net/xxx # Optional
+```
+
+**Features**:
+
+- ✅ Automatic image optimization
+- ✅ Format conversion (WebP, AVIF)
+- ✅ Variants (different sizes)
+- ✅ Signed URLs (with signing key)
+- ❌ Images only
+- ❌ No multipart uploads
+
+### Multi-Provider Setup
+
+**Best for**: Using different providers for different file types
+
+```bash
+STORAGE_PROVIDER=multi
+
+# Configure multiple providers
+VERCEL_BLOB_READ_WRITE_TOKEN=vercel_blob_rw_xxxxx
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET=my-bucket
+CLOUDFLARE_IMAGES_ACCOUNT_ID=your-account-id
+CLOUDFLARE_IMAGES_API_TOKEN=your-api-token
+```
+
+```typescript
+import { multiStorage } from "@repo/storage/server";
+
+// Upload to specific provider
+await multiStorage.upload("images/photo.jpg", imageFile, {
+  provider: "cloudflare-images" // Route to Cloudflare Images
+});
+
+await multiStorage.upload("documents/file.pdf", pdfFile, {
+  provider: "r2-legacy" // Route to Cloudflare R2
+});
+
+// Or use automatic routing (configured in env)
+await multiStorage.upload("images/photo.jpg", imageFile); // → Cloudflare Images
+await multiStorage.upload("documents/file.pdf", pdfFile); // → Cloudflare R2
+```
+
+---
+
+## Security Best Practices
+
+### 1. Enable Authentication
+
+**Always enable authentication in production:**
+
+```bash
+STORAGE_ENFORCE_AUTH=true
+```
+
+```typescript
+// Server action automatically checks authentication
+export async function uploadUserFile(file: File) {
+  // If not authenticated, returns { success: false, error: 'Unauthorized' }
+  const result = await uploadMediaAction(`user-files/${file.name}`, file);
+  return result;
+}
+```
+
+### 2. Implement Authorization
+
+**Check resource ownership:**
+
+```typescript
+import { getSession } from "@repo/storage/server/next";
+
+export async function uploadProductImage(productId: string, file: File) {
+  const session = await getSession();
+  if (!session?.user) {
+    throw new Error("Unauthorized");
+  }
+
+  // Check if user owns this product
+  const hasAccess = await checkProductAccess(session.user.id, productId, "write");
+  if (!hasAccess) {
+    throw new Error("Forbidden");
+  }
+
+  // Proceed with upload
+  const result = await uploadMediaAction(`products/${productId}/${file.name}`, file);
+
+  return result;
+}
+```
+
+### 3. Validate All Inputs
+
+**Always validate file size and type:**
+
+```typescript
+const result = await uploadMediaAction(key, file, {
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  allowedMimeTypes: ["image/jpeg", "image/png", "image/webp", "image/gif"]
+});
+```
+
+### 4. Enable Rate Limiting
+
+```bash
+STORAGE_ENABLE_RATE_LIMIT=true
+STORAGE_RATE_LIMIT_REQUESTS=100
+STORAGE_RATE_LIMIT_WINDOW_MS=60000 # 1 minute
+```
+
+### 5. Sanitize File Paths
+
+**Never trust user-provided filenames:**
+
+```typescript
+import { sanitizeStorageKey } from "@repo/storage/keys";
+
+const userFilename = req.query.filename; // Untrusted input
+const safeFilename = sanitizeStorageKey(userFilename);
+const key = `uploads/${safeFilename}`;
+
+await storage.upload(key, file);
+```
+
+### 6. Use HTTPS Only
+
+**For bulk imports, only allow HTTPS URLs:**
+
+```typescript
+// SSRF protection built into bulkImportFromUrlsAction
+const result = await bulkImportFromUrlsAction([
+  {
+    sourceUrl: "https://example.com/file.jpg", // ✅ HTTPS only
+    destinationKey: "imports/file.jpg"
+  }
+]);
+```
+
+---
+
+## API Reference
+
+### Client Exports
+
+```typescript
+import { upload, handleUpload } from "@repo/storage/client";
+import { uploadMultipleFiles } from "@repo/storage/client/next";
+```
+
+- `upload(pathname, body, options)` - Upload file to storage
+- `handleUpload(options)` - Get upload handler for form submissions
+- `uploadMultipleFiles(files, options)` - Upload multiple files with progress
+
+### Server Exports
+
+```typescript
+import {
+  storage,
+  multiStorage,
+  uploadMediaAction,
+  deleteMediaAction,
+  bulkDeleteMediaAction,
+  getStorage
+} from "@repo/storage/server/next";
+```
+
+- `storage` - Primary storage provider instance
+- `multiStorage` - Multi-provider manager
+- `uploadMediaAction()` - Server action for uploads
+- `deleteMediaAction()` - Server action for deletion
+- `bulkDeleteMediaAction()` - Bulk delete operation
+- `getStorage()` - Get storage provider instance
+
+### Edge Runtime Exports
+
+```typescript
+import { storage } from "@repo/storage/server/edge";
+```
+
+**Note**: Edge runtime only supports Vercel Blob and Cloudflare Images (no R2 due to Node.js dependency).
+
+### Utility Exports
+
+```typescript
+import { sanitizeStorageKey, validateStorageKey } from "@repo/storage/keys";
+import { env } from "@repo/storage/env";
+import type { StorageObject, UploadOptions } from "@repo/storage/types";
+```
+
+---
+
+## Migration Guide
+
+### Migrating from Vercel Blob to Cloudflare R2
+
+**1. Export existing files:**
+
+```typescript
+import { storage } from "@repo/storage/server";
+
+async function exportFiles() {
+  const files = await storage.list({ prefix: "uploads/" });
+
+  for (const file of files) {
+    const blob = await storage.download(file.key);
+    // Save locally or upload to new provider
+    await fs.writeFile(`./exports/${file.key}`, blob);
+  }
+}
+```
+
+**2. Update environment variables:**
+
+```bash
+# Before
+STORAGE_PROVIDER=vercel-blob
+VERCEL_BLOB_READ_WRITE_TOKEN=xxx
+
+# After
+STORAGE_PROVIDER=cloudflare-r2
+R2_ACCOUNT_ID=xxx
+R2_ACCESS_KEY_ID=xxx
+R2_SECRET_ACCESS_KEY=xxx
+R2_BUCKET=my-bucket
+```
+
+**3. Import files to new provider:**
+
+```typescript
+import { storage } from "@repo/storage/server";
+import fs from "fs/promises";
+
+async function importFiles() {
+  const files = await fs.readdir("./exports");
+
+  for (const filename of files) {
+    const data = await fs.readFile(`./exports/${filename}`);
+    await storage.upload(filename, data);
+  }
+}
+```
+
+**4. Update database records:**
+
+```typescript
+// Update URLs in database
+await db.media.updateMany({
+  data: {
+    url: db.raw("REPLACE(url, 'blob.vercel-storage.com', 'r2.cloudflarestorage.com')")
+  }
+});
+```
+
+---
+
+## Troubleshooting
+
+### "Storage provider configuration is incomplete"
+
+**Cause**: Missing required environment variables for selected provider.
+
+**Solution**: Check that all required variables are set:
+
+```bash
+# For Vercel Blob
+STORAGE_PROVIDER=vercel-blob
+VERCEL_BLOB_READ_WRITE_TOKEN=xxx
+
+# For Cloudflare R2
+STORAGE_PROVIDER=cloudflare-r2
+R2_ACCOUNT_ID=xxx
+R2_ACCESS_KEY_ID=xxx
+R2_SECRET_ACCESS_KEY=xxx
+R2_BUCKET=xxx
+```
+
+### "Rate limit exceeded"
+
+**Cause**: Too many requests in configured time window.
+
+**Solution**: Increase rate limit or add backoff logic:
+
+```bash
+STORAGE_RATE_LIMIT_REQUESTS=200 # Increase from 100
+STORAGE_RATE_LIMIT_WINDOW_MS=60000
+```
+
+### "Invalid storage key"
+
+**Cause**: Key contains invalid characters or path traversal.
+
+**Solution**: Use `sanitizeStorageKey`:
+
+```typescript
+import { sanitizeStorageKey } from "@repo/storage/keys";
+
+const key = sanitizeStorageKey(userInput);
+```
+
+### Edge runtime errors with R2
+
+**Cause**: Cloudflare R2 uses Node.js AWS SDK which is not edge-compatible.
+
+**Solution**: Use `@repo/storage/server/edge` which only includes edge-compatible providers:
+
+```typescript
+// ❌ Don't use in edge runtime
+import { storage } from "@repo/storage/server";
+
+// ✅ Use edge-compatible export
+import { storage } from "@repo/storage/server/edge";
+```
+
+### "File size exceeds maximum"
+
+**Cause**: File larger than configured limit.
+
+**Solution**: Increase limit or use multipart upload:
+
+```bash
+STORAGE_MAX_FILE_SIZE=209715200 # 200MB
+```
+
+Or use multipart for large files:
+
+```typescript
+import { createMultipartUploadManager } from "@repo/storage/server";
+
+const manager = createMultipartUploadManager(storage, key, largeFile);
+await manager.upload();
+```
+
+---
+
+## Testing
+
+Run tests:
+
+```bash
+pnpm test          # Run all tests
+pnpm test:watch    # Watch mode
+pnpm test:coverage # With coverage report
+```
+
+**Test Structure**:
+
+```
+__tests__/
+├── unit/                   # Unit tests
+├── integration/            # Integration tests
+├── shared/                 # Shared test utilities
+└── test-utils/             # Test factories and helpers
+```
+
+**Coverage**: 38 test files covering:
+
+- Provider implementations
+- Server actions
+- Client utilities
+- Validation logic
+- Error handling
+- Edge cases
+
+---
+
+## Performance
+
+### Benchmarks
+
+**Upload Performance** (1MB file):
+
+- Vercel Blob: ~200ms
+- Cloudflare R2: ~350ms
+- Cloudflare Images: ~250ms
+
+**List Performance** (100 files):
+
+- Vercel Blob: ~150ms (without N+1 query fix)
+- Cloudflare R2: ~100ms
+- Cloudflare Images: ~120ms
+
+**Note**: After implementing N+1 query fix (AUDIT_FINDINGS #7), Vercel Blob list performance improves to ~15ms.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
+
+### Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
+
+# Check for circular dependencies
+pnpm circular
+
+# Find unused code
+pnpm knip
+```
+
+---
+
+## Related Documentation
+
+- **[AUDIT_FINDINGS.md](./AUDIT_FINDINGS.md)** - Comprehensive security and code quality audit
+- **[AUDIT_REPORT.md](./AUDIT_REPORT.md)** - Original audit with 47 identified issues
+- **[SECURITY_FIXES.md](./SECURITY_FIXES.md)** - Security improvements tracking
+- **[Examples](./examples/)** - Real-world usage examples
+- **[Monorepo Docs](../../apps/docs/packages/storage.mdx)** - Full documentation site
+
+---
+
+## License
+
+Internal package for monorepo use only.
+
+---
+
+## Support
+
+For questions or issues:
+
+1. Check [AUDIT_FINDINGS.md](./AUDIT_FINDINGS.md) and [Troubleshooting](#troubleshooting)
+2. Review [examples](./examples/)
+3. Contact platform team
+
+---
+
+**Version**: Internal workspace package **Maintained by**: Platform Team **Last Updated**: 2025-11-16
+
+## 📚 Comprehensive Documentation
+
+For detailed documentation, see:
+
+- **[Audit Reports](../../apps/docs/content/docs/audits/storage/)** - Comprehensive audits, fixes, and security reviews
+- **[Technical Guides](../../apps/docs/content/docs/packages/storage/)** - Implementation guides and best practices
+
+All comprehensive documentation has been centralized in the docs app.