@bloomneo/appkit 1.2.9

package/dist/security/security.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Core security class with CSRF, rate limiting, sanitization, and encryption
+ * @module @bloomneo/appkit/security
+ * @file src/security/security.ts
+ *
+ * @llm-rule WHEN: Building apps that need security protection (CSRF, rate limiting, input sanitization, encryption)
+ * @llm-rule AVOID: Using directly - always get instance via securityClass.get()
+ * @llm-rule NOTE: Provides enterprise-grade security with CSRF tokens, rate limiting, XSS prevention, and AES-256-GCM encryption
+ */
+import type { SecurityConfig } from './defaults.js';
+export interface ExpressRequest {
+    method: string;
+    session?: any;
+    body?: any;
+    headers?: Record<string, string | string[] | undefined>;
+    query?: any;
+    ip?: string;
+    connection?: {
+        remoteAddress?: string;
+    };
+    csrfToken?: () => string;
+    [key: string]: any;
+}
+export interface ExpressResponse {
+    setHeader?: (name: string, value: string | number) => void;
+    [key: string]: any;
+}
+export interface ExpressNextFunction {
+    (error?: any): void;
+}
+export type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+export interface CSRFOptions {
+    secret?: string;
+    tokenField?: string;
+    headerField?: string;
+    expiryMinutes?: number;
+}
+export interface RateLimitOptions {
+    maxRequests?: number;
+    windowMs?: number;
+    message?: string;
+    keyGenerator?: (req: ExpressRequest) => string;
+}
+export interface InputOptions {
+    maxLength?: number;
+    trim?: boolean;
+    removeXSS?: boolean;
+}
+export interface HTMLOptions {
+    allowedTags?: string[];
+    stripAllTags?: boolean;
+}
+/**
+ * Security class with enterprise-grade protection functionality
+ */
+export declare class SecurityClass {
+    config: SecurityConfig;
+    private requestStore;
+    private cleanupInitialized;
+    constructor(config: SecurityConfig);
+    /**
+     * Creates CSRF protection middleware for forms and AJAX requests
+     * @llm-rule WHEN: Protecting forms and state-changing requests from CSRF attacks
+     * @llm-rule AVOID: Using without session middleware - CSRF requires sessions for token storage
+     * @llm-rule NOTE: Automatically validates tokens on POST/PUT/DELETE/PATCH requests, adds req.csrfToken() method
+     */
+    forms(options?: CSRFOptions): ExpressMiddleware;
+    /**
+     * Creates rate limiting middleware with configurable limits and windows
+     * @llm-rule WHEN: Protecting endpoints from abuse and brute force attacks
+     * @llm-rule AVOID: Using same limits for all endpoints - auth should have stricter limits than API
+     * @llm-rule NOTE: Uses in-memory storage with automatic cleanup, sets standard rate limit headers
+     */
+    requests(maxRequests?: number, windowMs?: number, options?: RateLimitOptions): ExpressMiddleware;
+    /**
+     * Cleans text input with XSS prevention and length limiting
+     * @llm-rule WHEN: Processing any user text input before storage or display
+     * @llm-rule AVOID: Storing raw user input - always clean to prevent XSS attacks
+     * @llm-rule NOTE: Removes dangerous patterns like <script>, javascript:, event handlers
+     */
+    input(text: any, options?: InputOptions): string;
+    /**
+     * Cleans HTML content allowing only specified safe tags
+     * @llm-rule WHEN: Processing user HTML content like rich text editor input
+     * @llm-rule AVOID: Allowing all HTML tags - only whitelist safe formatting tags
+     * @llm-rule NOTE: Removes script, iframe, object tags and dangerous attributes like onclick
+     */
+    html(html: any, options?: HTMLOptions): string;
+    /**
+     * Escapes HTML special characters for safe display in HTML content
+     * @llm-rule WHEN: Displaying user text content in HTML without allowing any HTML tags
+     * @llm-rule AVOID: Direct interpolation of user content in HTML - always escape first
+     * @llm-rule NOTE: Converts &, <, >, quotes to HTML entities for safe display
+     */
+    escape(text: any): string;
+    /**
+     * Encrypts sensitive data using AES-256-GCM with authentication
+     * @llm-rule WHEN: Storing sensitive data like SSNs, credit cards, personal info
+     * @llm-rule AVOID: Storing sensitive data in plain text - always encrypt before database storage
+     * @llm-rule NOTE: Uses random IV per encryption, includes authentication tag to prevent tampering
+     */
+    encrypt(data: string | Buffer, key?: string | Buffer, associatedData?: Buffer): string;
+    /**
+     * Decrypts previously encrypted data with authentication verification
+     * @llm-rule WHEN: Retrieving sensitive data that was encrypted with encrypt() method
+     * @llm-rule AVOID: Using with data not encrypted by this module - will fail authentication
+     * @llm-rule NOTE: Automatically verifies authentication tag to detect tampering
+     */
+    decrypt(encryptedData: string, key?: string | Buffer, associatedData?: Buffer): string;
+    /**
+     * Generates a cryptographically secure 256-bit encryption key
+     * @llm-rule WHEN: Setting up encryption for the first time or rotating keys
+     * @llm-rule AVOID: Using weak or predictable keys - always use this method for key generation
+     * @llm-rule NOTE: Returns 64-character hex string suitable for VOILA_SECURITY_ENCRYPTION_KEY
+     */
+    generateKey(): string;
+    /**
+     * Generates a cryptographically secure CSRF token
+     */
+    private generateCSRFToken;
+    /**
+     * Verifies CSRF token using timing-safe comparison
+     */
+    private verifyCSRFToken;
+    /**
+     * Gets unique identifier for the client
+     */
+    private getClientKey;
+    /**
+     * Initializes cleanup interval for memory management
+     */
+    private initializeCleanup;
+    /**
+     * Validates encryption key format and length
+     */
+    private validateEncryptionKey;
+}
+//# sourceMappingURL=security.d.ts.map

package/dist/security/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/security/security.ts"],"names":[],"mappings":"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"}

package/dist/security/security.js

@@ -0,0 +1,419 @@
+/**
+ * Core security class with CSRF, rate limiting, sanitization, and encryption
+ * @module @bloomneo/appkit/security
+ * @file src/security/security.ts
+ *
+ * @llm-rule WHEN: Building apps that need security protection (CSRF, rate limiting, input sanitization, encryption)
+ * @llm-rule AVOID: Using directly - always get instance via securityClass.get()
+ * @llm-rule NOTE: Provides enterprise-grade security with CSRF tokens, rate limiting, XSS prevention, and AES-256-GCM encryption
+ */
+import crypto from 'crypto';
+import { createSecurityError } from './defaults.js';
+/**
+ * Security class with enterprise-grade protection functionality
+ */
+export class SecurityClass {
+    config;
+    requestStore;
+    cleanupInitialized;
+    constructor(config) {
+        this.config = config;
+        this.requestStore = new Map();
+        this.cleanupInitialized = false;
+    }
+    /**
+     * Creates CSRF protection middleware for forms and AJAX requests
+     * @llm-rule WHEN: Protecting forms and state-changing requests from CSRF attacks
+     * @llm-rule AVOID: Using without session middleware - CSRF requires sessions for token storage
+     * @llm-rule NOTE: Automatically validates tokens on POST/PUT/DELETE/PATCH requests, adds req.csrfToken() method
+     */
+    forms(options = {}) {
+        const csrfSecret = options.secret || this.config.csrf.secret;
+        if (!csrfSecret) {
+            throw createSecurityError('CSRF secret required. Set VOILA_SECURITY_CSRF_SECRET or VOILA_AUTH_SECRET environment variable', 500);
+        }
+        const tokenField = options.tokenField || this.config.csrf.tokenField;
+        const headerField = options.headerField || this.config.csrf.headerField;
+        const expiryMinutes = options.expiryMinutes || this.config.csrf.expiryMinutes;
+        return (req, res, next) => {
+            // Ensure session exists
+            if (!req.session || typeof req.session !== 'object') {
+                const error = createSecurityError('Session required for CSRF protection', 500);
+                return next(error);
+            }
+            // Add token generation method to request
+            req.csrfToken = () => this.generateCSRFToken(req.session, expiryMinutes);
+            // Skip CSRF verification for safe HTTP methods
+            if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) {
+                return next();
+            }
+            // Extract token from request
+            const token = (req.body && req.body[tokenField]) ||
+                (req.headers && req.headers[headerField.toLowerCase()]) ||
+                (req.query && req.query[tokenField]);
+            // Verify token
+            if (!this.verifyCSRFToken(token, req.session)) {
+                const error = createSecurityError('Invalid or missing CSRF token', 403);
+                return next(error);
+            }
+            next();
+        };
+    }
+    /**
+     * Creates rate limiting middleware with configurable limits and windows
+     * @llm-rule WHEN: Protecting endpoints from abuse and brute force attacks
+     * @llm-rule AVOID: Using same limits for all endpoints - auth should have stricter limits than API
+     * @llm-rule NOTE: Uses in-memory storage with automatic cleanup, sets standard rate limit headers
+     */
+    requests(maxRequests, windowMs, options = {}) {
+        // Handle argument polymorphism
+        if (typeof maxRequests === 'object') {
+            options = maxRequests;
+            maxRequests = options.maxRequests;
+            windowMs = options.windowMs;
+        }
+        else if (typeof windowMs === 'object') {
+            options = windowMs;
+            windowMs = options.windowMs;
+        }
+        // Use provided values or config defaults
+        const max = maxRequests || this.config.rateLimit.maxRequests;
+        const window = windowMs || this.config.rateLimit.windowMs;
+        const message = options.message || this.config.rateLimit.message;
+        const keyGenerator = options.keyGenerator || this.getClientKey;
+        // Validate configuration
+        if (max < 0 || window <= 0) {
+            throw createSecurityError('Invalid rate limit configuration', 500);
+        }
+        // Initialize cleanup for memory management
+        this.initializeCleanup(window);
+        return (req, res, next) => {
+            const key = keyGenerator(req);
+            const now = Date.now();
+            // Get or create rate limit record
+            let record = this.requestStore.get(key);
+            if (!record) {
+                record = { count: 0, resetTime: now + window };
+                this.requestStore.set(key, record);
+            }
+            else if (now > record.resetTime) {
+                // Reset if window has passed
+                record.count = 0;
+                record.resetTime = now + window;
+            }
+            // Increment request count
+            record.count++;
+            // Set rate limit headers
+            if (res.setHeader) {
+                res.setHeader('X-RateLimit-Limit', max);
+                res.setHeader('X-RateLimit-Remaining', Math.max(0, max - record.count));
+                res.setHeader('X-RateLimit-Reset', Math.ceil(record.resetTime / 1000));
+            }
+            // Check if limit exceeded
+            if (record.count > max) {
+                const retryAfter = Math.ceil((record.resetTime - now) / 1000);
+                if (res.setHeader) {
+                    res.setHeader('Retry-After', retryAfter);
+                }
+                const error = createSecurityError(message, 429, {
+                    retryAfter,
+                    limit: max,
+                    remaining: 0,
+                    resetTime: record.resetTime,
+                });
+                return next(error);
+            }
+            next();
+        };
+    }
+    /**
+     * Cleans text input with XSS prevention and length limiting
+     * @llm-rule WHEN: Processing any user text input before storage or display
+     * @llm-rule AVOID: Storing raw user input - always clean to prevent XSS attacks
+     * @llm-rule NOTE: Removes dangerous patterns like <script>, javascript:, event handlers
+     */
+    input(text, options = {}) {
+        if (typeof text !== 'string') {
+            return '';
+        }
+        const maxLength = options.maxLength || this.config.sanitization.maxLength;
+        const trim = options.trim !== false;
+        const removeXSS = options.removeXSS !== false;
+        let result = text;
+        // Trim whitespace
+        if (trim) {
+            result = result.trim();
+        }
+        // Basic XSS prevention
+        if (removeXSS) {
+            result = result
+                .replace(/[<>]/g, '') // Remove angle brackets
+                .replace(/javascript:/gi, '') // Remove javascript: protocol
+                .replace(/on\w+\s*=/gi, '') // Remove inline event handlers
+                .replace(/data:/gi, '') // Remove data: protocol
+                .replace(/vbscript:/gi, '') // Remove vbscript: protocol
+                .replace(/expression\s*\(/gi, '') // Remove CSS expressions
+                .replace(/url\s*\(/gi, ''); // Remove CSS url() functions
+        }
+        // Length limiting
+        if (result.length > maxLength) {
+            result = result.substring(0, maxLength);
+        }
+        return result;
+    }
+    /**
+     * Cleans HTML content allowing only specified safe tags
+     * @llm-rule WHEN: Processing user HTML content like rich text editor input
+     * @llm-rule AVOID: Allowing all HTML tags - only whitelist safe formatting tags
+     * @llm-rule NOTE: Removes script, iframe, object tags and dangerous attributes like onclick
+     */
+    html(html, options = {}) {
+        if (typeof html !== 'string') {
+            return '';
+        }
+        const allowedTags = options.allowedTags || this.config.sanitization.allowedTags;
+        const stripAllTags = options.stripAllTags !== undefined
+            ? options.stripAllTags
+            : this.config.sanitization.stripAllTags;
+        let result = html;
+        // Strip all tags if requested
+        if (stripAllTags) {
+            return result.replace(/<[^>]*>/g, '');
+        }
+        // Remove dangerous elements
+        result = result
+            .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '') // Remove script tags
+            .replace(/<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe>/gi, '') // Remove iframe tags
+            .replace(/<object\b[^<]*(?:(?!<\/object>)<[^<]*)*<\/object>/gi, '') // Remove object tags
+            .replace(/<embed\b[^>]*>/gi, '') // Remove embed tags
+            .replace(/<form\b[^<]*(?:(?!<\/form>)<[^<]*)*<\/form>/gi, '') // Remove form tags
+            .replace(/\s+on\w+\s*=\s*["'][^"']*["']/gi, '') // Remove inline event handlers
+            .replace(/javascript\s*:/gi, '') // Remove javascript: protocol
+            .replace(/data\s*:/gi, '') // Remove data: protocol
+            .replace(/vbscript\s*:/gi, '') // Remove vbscript: protocol
+            .replace(/expression\s*\(/gi, ''); // Remove CSS expressions
+        // Filter allowed tags if specified
+        if (allowedTags.length > 0) {
+            try {
+                const allowedPattern = allowedTags
+                    .map(tag => tag.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&'))
+                    .join('|');
+                const tagPattern = new RegExp(`<(?!\/?(?:${allowedPattern})\\b)[^>]+>`, 'gi');
+                result = result.replace(tagPattern, '');
+            }
+            catch (error) {
+                console.warn('HTML sanitization: Invalid allowed tags, stripping all tags');
+                result = result.replace(/<[^>]*>/g, '');
+            }
+        }
+        return result;
+    }
+    /**
+     * Escapes HTML special characters for safe display in HTML content
+     * @llm-rule WHEN: Displaying user text content in HTML without allowing any HTML tags
+     * @llm-rule AVOID: Direct interpolation of user content in HTML - always escape first
+     * @llm-rule NOTE: Converts &, <, >, quotes to HTML entities for safe display
+     */
+    escape(text) {
+        if (typeof text !== 'string') {
+            return '';
+        }
+        const HTML_ESCAPE_MAP = {
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&#x27;',
+            '/': '&#x2F;',
+            '`': '&#x60;',
+            '=': '&#x3D;',
+        };
+        return text.replace(/[&<>"'/`=]/g, (char) => HTML_ESCAPE_MAP[char]);
+    }
+    /**
+     * Encrypts sensitive data using AES-256-GCM with authentication
+     * @llm-rule WHEN: Storing sensitive data like SSNs, credit cards, personal info
+     * @llm-rule AVOID: Storing sensitive data in plain text - always encrypt before database storage
+     * @llm-rule NOTE: Uses random IV per encryption, includes authentication tag to prevent tampering
+     */
+    encrypt(data, key, associatedData) {
+        if (!data) {
+            throw createSecurityError('Data to encrypt cannot be empty');
+        }
+        const encryptionKey = key || this.config.encryption.key;
+        if (!encryptionKey) {
+            throw createSecurityError('Encryption key required. Provide as argument or set VOILA_SECURITY_ENCRYPTION_KEY environment variable', 500);
+        }
+        this.validateEncryptionKey(encryptionKey);
+        const keyBuffer = typeof encryptionKey === 'string'
+            ? Buffer.from(encryptionKey, 'hex')
+            : encryptionKey;
+        try {
+            // Generate random IV for each encryption
+            const iv = crypto.randomBytes(this.config.encryption.ivLength);
+            const cipher = crypto.createCipheriv(this.config.encryption.algorithm, keyBuffer, iv);
+            // Set AAD if provided
+            if (associatedData) {
+                if (!Buffer.isBuffer(associatedData)) {
+                    throw createSecurityError('Associated data must be a Buffer');
+                }
+                cipher.setAAD(associatedData);
+            }
+            // Encrypt data
+            const dataBuffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+            let encrypted = cipher.update(dataBuffer);
+            encrypted = Buffer.concat([encrypted, cipher.final()]);
+            // Get authentication tag
+            const authTag = cipher.getAuthTag();
+            // Combine IV, ciphertext, and auth tag
+            return `${iv.toString('hex')}:${encrypted.toString('hex')}:${authTag.toString('hex')}`;
+        }
+        catch (error) {
+            throw createSecurityError(`Encryption failed: ${error.message}`, 500);
+        }
+    }
+    /**
+     * Decrypts previously encrypted data with authentication verification
+     * @llm-rule WHEN: Retrieving sensitive data that was encrypted with encrypt() method
+     * @llm-rule AVOID: Using with data not encrypted by this module - will fail authentication
+     * @llm-rule NOTE: Automatically verifies authentication tag to detect tampering
+     */
+    decrypt(encryptedData, key, associatedData) {
+        if (!encryptedData || typeof encryptedData !== 'string') {
+            throw createSecurityError('Encrypted data must be a non-empty string');
+        }
+        const decryptionKey = key || this.config.encryption.key;
+        if (!decryptionKey) {
+            throw createSecurityError('Decryption key required. Provide as argument or set VOILA_SECURITY_ENCRYPTION_KEY environment variable', 500);
+        }
+        this.validateEncryptionKey(decryptionKey);
+        const keyBuffer = typeof decryptionKey === 'string'
+            ? Buffer.from(decryptionKey, 'hex')
+            : decryptionKey;
+        // Parse encrypted data format
+        const parts = encryptedData.split(':');
+        if (parts.length !== 3) {
+            throw createSecurityError('Invalid encrypted data format. Expected IV:ciphertext:authTag');
+        }
+        try {
+            const iv = Buffer.from(parts[0], 'hex');
+            const encrypted = Buffer.from(parts[1], 'hex');
+            const authTag = Buffer.from(parts[2], 'hex');
+            // Validate component lengths
+            if (iv.length !== this.config.encryption.ivLength ||
+                authTag.length !== this.config.encryption.tagLength) {
+                throw createSecurityError('Invalid IV or authentication tag length');
+            }
+            // Create decipher
+            const decipher = crypto.createDecipheriv(this.config.encryption.algorithm, keyBuffer, iv);
+            // Set AAD if provided
+            if (associatedData) {
+                if (!Buffer.isBuffer(associatedData)) {
+                    throw createSecurityError('Associated data must be a Buffer');
+                }
+                decipher.setAAD(associatedData);
+            }
+            // Set authentication tag
+            decipher.setAuthTag(authTag);
+            // Decrypt data
+            let decrypted = decipher.update(encrypted);
+            decrypted = Buffer.concat([decrypted, decipher.final()]);
+            return decrypted.toString('utf8');
+        }
+        catch (error) {
+            if (error.code === 'EBADTAG') {
+                throw createSecurityError('Authentication failed: Data may be tampered with or incorrect key/AAD provided', 401);
+            }
+            throw createSecurityError(`Decryption failed: ${error.message}`, 500);
+        }
+    }
+    /**
+     * Generates a cryptographically secure 256-bit encryption key
+     * @llm-rule WHEN: Setting up encryption for the first time or rotating keys
+     * @llm-rule AVOID: Using weak or predictable keys - always use this method for key generation
+     * @llm-rule NOTE: Returns 64-character hex string suitable for VOILA_SECURITY_ENCRYPTION_KEY
+     */
+    generateKey() {
+        try {
+            return crypto.randomBytes(this.config.encryption.keyLength).toString('hex');
+        }
+        catch (error) {
+            throw createSecurityError(`Key generation failed: ${error.message}`, 500);
+        }
+    }
+    // Private helper methods
+    /**
+     * Generates a cryptographically secure CSRF token
+     */
+    generateCSRFToken(session, expiryMinutes) {
+        if (!session || typeof session !== 'object') {
+            throw createSecurityError('Session object required for CSRF token generation', 500);
+        }
+        const token = crypto.randomBytes(16).toString('hex');
+        session.csrfToken = token;
+        session.csrfTokenExpiry = Date.now() + expiryMinutes * 60 * 1000;
+        return token;
+    }
+    /**
+     * Verifies CSRF token using timing-safe comparison
+     */
+    verifyCSRFToken(token, session) {
+        if (!token || typeof token !== 'string' || !session?.csrfToken) {
+            return false;
+        }
+        // Check expiry
+        if (session.csrfTokenExpiry && Date.now() > session.csrfTokenExpiry) {
+            return false;
+        }
+        try {
+            const expectedBuffer = Buffer.from(session.csrfToken, 'hex');
+            const actualBuffer = Buffer.from(token, 'hex');
+            if (expectedBuffer.length !== actualBuffer.length) {
+                return false;
+            }
+            return crypto.timingSafeEqual(expectedBuffer, actualBuffer);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Gets unique identifier for the client
+     */
+    getClientKey = (req) => {
+        return req.ip ||
+            req.connection?.remoteAddress ||
+            (req.headers && req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+            'unknown';
+    };
+    /**
+     * Initializes cleanup interval for memory management
+     */
+    initializeCleanup(windowMs) {
+        if (this.cleanupInitialized)
+            return;
+        const cleanupInterval = Math.min(windowMs, 60 * 1000);
+        setInterval(() => {
+            const now = Date.now();
+            for (const [key, record] of this.requestStore.entries()) {
+                if (now > record.resetTime) {
+                    this.requestStore.delete(key);
+                }
+            }
+        }, cleanupInterval).unref();
+        this.cleanupInitialized = true;
+    }
+    /**
+     * Validates encryption key format and length
+     */
+    validateEncryptionKey(key) {
+        if (!key) {
+            throw createSecurityError('Encryption key is required', 500);
+        }
+        const keyBuffer = typeof key === 'string' ? Buffer.from(key, 'hex') : key;
+        if (keyBuffer.length !== this.config.encryption.keyLength) {
+            throw createSecurityError(`Invalid key length. Expected ${this.config.encryption.keyLength} bytes, got ${keyBuffer.length} bytes`, 500);
+        }
+    }
+}
+//# sourceMappingURL=security.js.map

package/dist/security/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/security/security.ts"],"names":[],"mappings":"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"}

package/dist/storage/defaults.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Smart defaults and environment validation for file storage with auto-strategy detection
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/defaults.ts
+ *
+ * @llm-rule WHEN: App startup - need to configure storage system and connection strategy
+ * @llm-rule AVOID: Calling multiple times - expensive environment parsing, use lazy loading in get()
+ * @llm-rule NOTE: Called once at startup, cached globally for performance
+ * @llm-rule NOTE: Auto-detects Local vs S3 vs R2 based on environment variables
+ */
+export interface LocalConfig {
+    dir: string;
+    baseUrl: string;
+    maxFileSize: number;
+    allowedTypes: string[];
+    createDirs: boolean;
+}
+export interface S3Config {
+    bucket: string;
+    region: string;
+    endpoint?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    forcePathStyle: boolean;
+    signedUrlExpiry: number;
+    cdnUrl?: string;
+}
+export interface R2Config {
+    bucket: string;
+    accountId: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    cdnUrl?: string;
+    signedUrlExpiry: number;
+}
+export interface StorageConfig {
+    strategy: 'local' | 's3' | 'r2';
+    local?: LocalConfig;
+    s3?: S3Config;
+    r2?: R2Config;
+    environment: {
+        isDevelopment: boolean;
+        isProduction: boolean;
+        isTest: boolean;
+        nodeEnv: string;
+    };
+}
+/**
+ * Gets smart defaults using environment variables with auto-strategy detection
+ * @llm-rule WHEN: App startup to get production-ready storage configuration
+ * @llm-rule AVOID: Calling repeatedly - expensive validation, cache the result
+ * @llm-rule NOTE: Auto-detects strategy: S3/R2 env vars → Cloud, nothing → Local
+ */
+export declare function getSmartDefaults(): StorageConfig;
+/**
+ * Gets storage configuration summary for debugging and health checks
+ * @llm-rule WHEN: Debugging storage configuration or building health check endpoints
+ * @llm-rule AVOID: Exposing sensitive connection details - this only shows safe info
+ */
+export declare function getConfigSummary(): {
+    strategy: string;
+    local: boolean;
+    s3: boolean;
+    r2: boolean;
+    environment: string;
+};
+/**
+ * Checks if cloud storage is available and properly configured
+ * @llm-rule WHEN: Conditional logic based on storage capabilities
+ * @llm-rule AVOID: Complex storage detection - just use storage normally, strategy handles it
+ */
+export declare function hasCloudStorage(): boolean;
+/**
+ * Gets recommended configuration for different deployment types
+ * @llm-rule WHEN: Setting up storage for specific deployment scenarios
+ * @llm-rule AVOID: Default config for specialized deployments - needs specific tuning
+ */
+export declare function getDeploymentConfig(type: 'development' | 'staging' | 'production'): Partial<StorageConfig>;
+//# sourceMappingURL=defaults.d.ts.map