@od-oneapp/storage 2026.1.1301

package/src/auth-helpers.ts

@@ -0,0 +1,386 @@
+/**
+ * @fileoverview Authentication and Authorization Utilities for Storage Actions
+ *
+ * This module provides authentication and authorization helpers for storage server actions.
+ * These functions should be implemented by the consuming application to integrate with
+ * the authentication system.
+ *
+ * NOTE: These are placeholder functions that should be replaced with actual implementations
+ * from your authentication package (e.g., @od-oneapp/auth, NextAuth, etc.)
+ *
+ * @module @od-oneapp/storage/auth-helpers
+ */
+
+import { logError, logWarn } from '@repo/shared/logs';
+
+import { safeEnv } from '../env';
+
+/**
+ * Retrieves the current authenticated user session
+ *
+ * This is a placeholder implementation that should be replaced with your actual
+ * authentication system integration (NextAuth, @od-oneapp/auth, Clerk, etc.).
+ *
+ * **Implementation Pattern:**
+ * ```typescript
+ * // Example with @od-oneapp/auth:
+ * const { auth } = await import('@od-oneapp/auth/server');
+ * return await auth();
+ *
+ * // Example with NextAuth:
+ * const { getServerSession } = await import('next-auth');
+ * return await getServerSession(authOptions);
+ * ```
+ *
+ * @returns Session object containing user info, or `null` if unauthenticated
+ *
+ * @example
+ * ```typescript
+ * export async function uploadMediaAction(key: string, data: Blob) {
+ *   'use server';
+ *
+ *   const session = await getSession();
+ *   if (!session?.user) {
+ *     return { success: false, error: 'Unauthorized' };
+ *   }
+ *
+ *   // Proceed with authenticated upload
+ *   const storage = getStorage();
+ *   const result = await storage.upload(key, data);
+ *
+ *   return { success: true, data: result };
+ * }
+ * ```
+ */
+export async function getSession(): Promise<{ user: { id: string; email?: string } } | null> {
+  // Permissive-by-default: return null (unauthenticated)
+  // Consuming actions should enforce auth based on env flags
+  try {
+    // If a real auth implementation is available, prefer it (optional dynamic import pattern)
+    // const { auth } = await import('@od-oneapp/auth/server');
+    // return await auth();
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Checks if a user has permission to manage a specific product
+ *
+ * This is a placeholder that returns `false` by default (deny-by-default security).
+ * Replace with your actual authorization logic that checks:
+ * - Product ownership
+ * - Role-based permissions (admin, editor, viewer)
+ * - Team/organization membership
+ *
+ * **Implementation Pattern:**
+ * ```typescript
+ * // Example with database check:
+ * const product = await db.product.findUnique({
+ *   where: { id: productId },
+ *   include: { team: { members: true } }
+ * });
+ *
+ * return product?.ownerId === userId ||
+ *        product?.team?.members.some(m => m.userId === userId && m.role === 'admin');
+ * ```
+ *
+ * @param userId - User ID to authorize
+ * @param productId - Product ID to check access for
+ * @returns `true` if user can manage the product, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * export async function deleteProductMediaAction(mediaId: string) {
+ *   'use server';
+ *
+ *   const session = await getSession();
+ *   if (!session?.user) {
+ *     return { success: false, error: 'Unauthorized' };
+ *   }
+ *
+ *   const media = await db.productMedia.findUnique({ where: { id: mediaId } });
+ *   if (!media) {
+ *     return { success: false, error: 'Not found' };
+ *   }
+ *
+ *   const canManage = await canUserManageProduct(session.user.id, media.productId);
+ *   if (!canManage) {
+ *     return { success: false, error: 'Forbidden' };
+ *   }
+ *
+ *   await getStorage().delete(media.storageKey);
+ *   return { success: true };
+ * }
+ * ```
+ */
+export async function canUserManageProduct(_userId: string, _productId: string): Promise<boolean> {
+  // Deny-by-default (restrictive): returns false until replaced with actual authorization logic
+  // Replace with actual authorization logic in the consuming app
+  return false;
+}
+
+/**
+ * Extracts client IP address or identifier for rate limiting
+ *
+ * This placeholder returns `'unknown'`. Implement proper IP extraction based on:
+ * - Proxy headers (X-Forwarded-For, X-Real-IP, CF-Connecting-IP)
+ * - Direct connection IP
+ * - User ID for authenticated rate limiting
+ *
+ * **Implementation Pattern:**
+ * ```typescript
+ * export function getClientIP(_request?: Request): string {
+ *   if (!request) return 'unknown';
+ *
+ *   // Cloudflare
+ *   const cfIP = request.headers.get('cf-connecting-ip');
+ *   if (cfIP) return cfIP;
+ *
+ *   // Behind proxy
+ *   const forwarded = request.headers.get('x-forwarded-for');
+ *   if (forwarded) return forwarded.split(',')[0]?.trim() || 'unknown';
+ *
+ *   // Direct connection
+ *   const realIP = request.headers.get('x-real-ip');
+ *   return realIP || 'unknown';
+ * }
+ * ```
+ *
+ * @param request - Optional Request object to extract IP from
+ * @returns Client IP address or `'unknown'` if not determinable
+ *
+ * @example
+ * ```typescript
+ * export async function uploadAction(request: Request, data: FormData) {
+ *   'use server';
+ *
+ *   const clientIP = getClientIP(request);
+ *   const rateLimit = await checkRateLimit(
+ *     clientIP,
+ *     'storage:upload',
+ *     100, // max requests
+ *     60000 // per minute
+ *   );
+ *
+ *   if (!rateLimit.allowed) {
+ *     return {
+ *       success: false,
+ *       error: 'Rate limit exceeded',
+ *       resetAt: rateLimit.resetAt
+ *     };
+ *   }
+ *
+ *   // Process upload...
+ * }
+ * ```
+ */
+export function getClientIP(_request?: Request): string {
+  // TODO: Implement IP extraction from request headers
+  // Example:
+  // if (request) {
+  //   return request.headers.get('x-forwarded-for')?.split(',')[0] ||
+  //          request.headers.get('x-real-ip') ||
+  //          'unknown';
+  // }
+
+  // Fallback for server actions (may need to pass request through)
+  return 'unknown';
+}
+
+/**
+ * Checks if an identifier has exceeded rate limits for a storage action
+ *
+ * This placeholder always allows requests when `STORAGE_ENABLE_RATE_LIMIT=false`.
+ * When enabled, implement with Redis, Upstash, or in-memory store.
+ *
+ * **Implementation Pattern (Redis):**
+ * ```typescript
+ * import { Redis } from '@upstash/redis';
+ *
+ * export async function checkRateLimit(
+ *   identifier: string,
+ *   action: string,
+ *   maxRequests: number,
+ *   windowMs: number
+ * ) {
+ *   const redis = Redis.fromEnv();
+ *   const key = `ratelimit:${action}:${identifier}`;
+ *
+ *   const count = await redis.incr(key);
+ *   if (count === 1) {
+ *     await redis.pexpire(key, windowMs);
+ *   }
+ *
+ *   const ttl = await redis.pttl(key);
+ *   const resetAt = new Date(Date.now() + ttl);
+ *
+ *   return {
+ *     allowed: count <= maxRequests,
+ *     remaining: Math.max(0, maxRequests - count),
+ *     resetAt
+ *   };
+ * }
+ * ```
+ *
+ * @param identifier - Unique identifier (IP address, user ID, API key)
+ * @param action - Action key for rate limiting (e.g., `'storage:upload'`, `'storage:delete'`)
+ * @param maxRequests - Maximum requests allowed in the time window
+ * @param windowMs - Time window in milliseconds (e.g., 60000 for 1 minute)
+ * @returns Rate limit status with allowed flag, remaining count, and reset time
+ *
+ * @example
+ * ```typescript
+ * export async function uploadMediaAction(key: string, data: Blob) {
+ *   'use server';
+ *
+ *   const session = await getSession();
+ *   const identifier = session?.user.id || getClientIP();
+ *
+ *   const limit = await checkRateLimit(identifier, 'storage:upload', 100, 60000);
+ *   if (!limit.allowed) {
+ *     return {
+ *       success: false,
+ *       error: `Rate limit exceeded. ${limit.remaining} requests remaining. Resets at ${limit.resetAt.toISOString()}`,
+ *     };
+ *   }
+ *
+ *   const storage = getStorage();
+ *   const result = await storage.upload(key, data);
+ *   return { success: true, data: result };
+ * }
+ * ```
+ */
+export async function checkRateLimit(
+  identifier: string,
+  action: string,
+  maxRequests: number,
+  windowMs: number,
+): Promise<{ allowed: boolean; remaining: number; resetAt: Date }> {
+  // Check feature flag to decide behavior
+  const { safeEnv } = await import('../env');
+  const env = safeEnv();
+
+  if (!env.STORAGE_ENABLE_RATE_LIMIT) {
+    // Permissive: allow
+    return {
+      allowed: true,
+      remaining: maxRequests,
+      resetAt: new Date(Date.now() + windowMs),
+    };
+  }
+
+  // If enabled but no implementation, allow but with zero remaining to encourage integration
+  return {
+    allowed: true,
+    remaining: Math.max(0, maxRequests - 1),
+    resetAt: new Date(Date.now() + windowMs),
+  };
+}
+
+/**
+ * Validate a CSRF token according to runtime enforcement settings.
+ *
+ * If the environment flag `STORAGE_ENFORCE_CSRF` is false or the environment is unavailable, validation is permissive and this function returns `true`. When enforcement is enabled, the function returns `true` only if `token` is a non-empty string.
+ *
+ * @param token - CSRF token to validate
+ * @param request - Optional request object that consuming applications may inspect when implementing real validation
+ * @returns `true` if the token is considered valid (or enforcement is disabled / env unavailable), `false` otherwise
+ * @deprecated Use validateCSRFOrigin() for better origin-based validation
+ */
+export function validateCSRFToken(token: string, _request?: Request): boolean {
+  // Enforce behavior based on env flag
+  try {
+    const env = safeEnv();
+    if (!env.STORAGE_ENFORCE_CSRF) {
+      // Permissive-by-default: skip CSRF enforcement
+      return true;
+    }
+  } catch {
+    // If env not available, be permissive in package context
+    return true;
+  }
+
+  // If enforcement is enabled but no real validation is available, fail closed
+  return typeof token === 'string' && token.length > 0;
+}
+
+/**
+ * Validates CSRF protection by checking request origin matches host
+ *
+ * Next.js has built-in origin checking for Server Actions, but this adds
+ * explicit validation for defense-in-depth security.
+ *
+ * This function validates:
+ * - The request origin header matches the host header
+ * - Optional x-csrf-token header if provided
+ *
+ * @returns `true` if CSRF validation passes or is disabled, `false` if validation fails
+ *
+ * @example
+ * ```typescript
+ * export async function uploadMediaAction(...) {
+ *   'use server';
+ *
+ *   const csrfValid = await validateCSRFOrigin();
+ *   if (!csrfValid) {
+ *     return { success: false, error: 'Invalid request origin' };
+ *   }
+ *   // ... proceed with action
+ * }
+ * ```
+ */
+export async function validateCSRFOrigin(): Promise<boolean> {
+  const env = safeEnv();
+
+  if (!env.STORAGE_ENFORCE_CSRF) {
+    return true; // CSRF validation disabled
+  }
+
+  try {
+    const { headers } = await import('next/headers');
+    const headersList = await headers();
+    const origin = headersList.get('origin');
+    const host = headersList.get('host');
+
+    // Validate origin matches host
+    if (origin && host) {
+      try {
+        const originUrl = new URL(origin);
+        const expectedOrigin = `${originUrl.protocol}//${host}`;
+
+        if (origin !== expectedOrigin) {
+          logWarn('CSRF validation failed: origin mismatch', {
+            origin,
+            expectedOrigin,
+            host,
+          });
+          return false;
+        }
+      } catch (error) {
+        logError('CSRF validation error: invalid origin URL', {
+          origin,
+          error,
+        });
+        return false;
+      }
+    }
+
+    // Additional: Validate custom CSRF token if provided
+    const csrfToken = headersList.get('x-csrf-token');
+    if (csrfToken) {
+      // Basic validation - consuming apps should enhance this with session validation
+      // For now, just check it's a non-empty string
+      if (typeof csrfToken !== 'string' || csrfToken.length === 0) {
+        return false;
+      }
+    }
+
+    return true;
+  } catch (error) {
+    // If headers() fails (not in Next.js context), be permissive for package usage
+    logWarn('CSRF validation skipped: not in Next.js context', { error });
+    return true;
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview Storage Provider Capabilities Utilities
+ *
+ * Provides utilities for checking storage provider capabilities and feature support.
+ * Helps determine which features are available for each provider.
+ *
+ * @module @repo/storage/capabilities
+ */
+
+import { DEFAULT_STORAGE_CAPABILITIES, MULTIPART_THRESHOLDS } from './constants';
+
+import type { StorageCapabilities, StorageProvider } from '../types';
+
+/**
+ * Check if a storage provider has a specific capability
+ * @param provider - The storage provider to check
+ * @param capability - The capability to check for
+ * @returns True if the provider supports the capability
+ */
+export function hasCapability(
+  provider: StorageProvider,
+  capability: keyof StorageCapabilities,
+): boolean {
+  const capabilities = provider.getCapabilities?.();
+  return capabilities?.[capability] ?? false;
+}
+
+/**
+ * Check if a storage provider supports multiple capabilities
+ * @param provider - The storage provider to check
+ * @param capabilities - Array of capabilities to check for
+ * @returns True if the provider supports all capabilities
+ */
+export function hasAllCapabilities(
+  provider: StorageProvider,
+  capabilities: Array<keyof StorageCapabilities>,
+): boolean {
+  return capabilities.every(capability => hasCapability(provider, capability));
+}
+
+/**
+ * Check if a storage provider supports any of the specified capabilities
+ * @param provider - The storage provider to check
+ * @param capabilities - Array of capabilities to check for
+ * @returns True if the provider supports at least one capability
+ */
+export function hasAnyCapability(
+  provider: StorageProvider,
+  capabilities: Array<keyof StorageCapabilities>,
+): boolean {
+  return capabilities.some(capability => hasCapability(provider, capability));
+}
+
+/**
+ * Get all capabilities supported by a storage provider
+ * @param provider - The storage provider to check
+ * @returns Object with all capabilities and their support status
+ */
+export function getProviderCapabilities(provider: StorageProvider): StorageCapabilities {
+  return provider.getCapabilities?.() ?? { ...DEFAULT_STORAGE_CAPABILITIES };
+}
+
+/**
+ * Get a human-readable description of provider capabilities
+ * @param provider - The storage provider to describe
+ * @returns String describing the provider's capabilities
+ */
+export function describeProviderCapabilities(provider: StorageProvider): string {
+  const capabilities = getProviderCapabilities(provider);
+  const supportedFeatures: string[] = [];
+  const unsupportedFeatures: string[] = [];
+
+  if (capabilities.multipart) supportedFeatures.push('multipart uploads');
+  else unsupportedFeatures.push('multipart uploads');
+
+  if (capabilities.presignedUrls) supportedFeatures.push('presigned URLs');
+  else unsupportedFeatures.push('presigned URLs');
+
+  if (capabilities.progressTracking) supportedFeatures.push('progress tracking');
+  else unsupportedFeatures.push('progress tracking');
+
+  if (capabilities.abortSignal) supportedFeatures.push('abort signals');
+  else unsupportedFeatures.push('abort signals');
+
+  if (capabilities.metadata) supportedFeatures.push('metadata');
+  else unsupportedFeatures.push('metadata');
+
+  if (capabilities.customDomains) supportedFeatures.push('custom domains');
+  else unsupportedFeatures.push('custom domains');
+
+  if (capabilities.edgeCompatible) supportedFeatures.push('edge runtime');
+  else unsupportedFeatures.push('edge runtime');
+
+  let description = `Provider supports: ${supportedFeatures.join(', ')}`;
+
+  if (unsupportedFeatures.length > 0) {
+    description += `\nProvider does not support: ${unsupportedFeatures.join(', ')}`;
+  }
+
+  return description;
+}
+
+/**
+ * Validate that a provider supports the required capabilities for an operation
+ * @param provider - The storage provider to validate
+ * @param requiredCapabilities - Capabilities required for the operation
+ * @throws Error if provider doesn't support required capabilities
+ */
+export function validateProviderCapabilities(
+  provider: StorageProvider,
+  requiredCapabilities: Array<keyof StorageCapabilities>,
+): void {
+  const missingCapabilities = requiredCapabilities.filter(
+    capability => !hasCapability(provider, capability),
+  );
+
+  if (missingCapabilities.length > 0) {
+    const providerName = provider.constructor.name;
+    throw new Error(
+      `Provider ${providerName} does not support required capabilities: ${missingCapabilities.join(', ')}`,
+    );
+  }
+}
+
+/**
+ * Get the best provider for a specific use case based on capabilities
+ * @param providers - Array of storage providers to choose from
+ * @param requiredCapabilities - Capabilities required for the use case
+ * @returns The best provider or null if none meet the requirements
+ */
+export function getBestProvider(
+  providers: StorageProvider[],
+  requiredCapabilities: Array<keyof StorageCapabilities>,
+): StorageProvider | null {
+  const suitableProviders = providers.filter(provider =>
+    hasAllCapabilities(provider, requiredCapabilities),
+  );
+
+  if (suitableProviders.length === 0) {
+    return null;
+  }
+
+  // If multiple providers are suitable, prefer edge-compatible ones
+  const edgeCompatible = suitableProviders.filter(provider =>
+    hasCapability(provider, 'edgeCompatible'),
+  );
+
+  return edgeCompatible.length > 0 ? (edgeCompatible[0] ?? null) : (suitableProviders[0] ?? null);
+}
+
+/**
+ * Builds a map from provider names to their reported storage capabilities.
+ *
+ * @param providers - Array of entries each containing a `name` (used as the map key) and a `provider` instance
+ * @returns A mapping from each provider name to its `StorageCapabilities`
+ */
+export function getCapabilityMatrix(
+  providers: Array<{ name: string; provider: StorageProvider }>,
+): Record<string, StorageCapabilities> {
+  const matrix: Record<string, StorageCapabilities> = {};
+
+  for (const { name, provider } of providers) {
+    matrix[name] = getProviderCapabilities(provider);
+  }
+
+  return matrix;
+}
+
+/**
+ * Evaluate a storage provider's suitability for a specific file and produce actionable recommendations and warnings.
+ *
+ * @param provider - The storage provider to evaluate
+ * @param fileSize - File size in bytes
+ * @param fileType - MIME type of the file
+ * @returns An object with `suitable` (`true` if there are no warnings, `false` otherwise), `recommendations` (suggested actions to improve handling), and `warnings` (issues that reduce suitability)
+ */
+export function checkProviderSuitability(
+  provider: StorageProvider,
+  fileSize: number,
+  fileType: string,
+): {
+  suitable: boolean;
+  recommendations: string[];
+  warnings: string[];
+} {
+  const capabilities = getProviderCapabilities(provider);
+  const recommendations: string[] = [];
+  const warnings: string[] = [];
+
+  // Check file size suitability
+  if (fileSize > MULTIPART_THRESHOLDS.SMALL_FILE) {
+    // > 100MB
+    if (!capabilities.multipart) {
+      warnings.push('Large file detected but provider does not support multipart uploads');
+    } else {
+      recommendations.push('Use multipart upload for this large file');
+    }
+  }
+
+  // Check file type suitability
+  if (fileType.startsWith('image/')) {
+    if (capabilities.metadata) {
+      recommendations.push('Consider storing image metadata for better organization');
+    }
+  }
+
+  if (fileType.startsWith('video/')) {
+    if (!capabilities.multipart) {
+      warnings.push('Video files are typically large and benefit from multipart uploads');
+    }
+  }
+
+  // Check edge compatibility
+  if (fileType.startsWith('text/') && !capabilities.edgeCompatible) {
+    recommendations.push('Text files could be processed in edge runtime for better performance');
+  }
+
+  const suitable = warnings.length === 0;
+
+  return {
+    suitable,
+    recommendations,
+    warnings,
+  };
+}