🔐 Security & Encryption

• Data Encryption: Secure encryption and decryption utilities with IV key support
• JWT Tokens: Token generation and validation
• Barcode Generation: Create barcodes using ZXing.Net
• Shared Link Security: Time-based expiry for secure file sharing
• File Validation: Prevent malicious file uploads with extension and size restrictions

📊 Data Utilities

• JSON Processing: Advanced JSON serialization and deserialization helpers
• Date Handling: Comprehensive date and time utilities
• String Operations: String manipulation and formatting tools
• Image Processing: Image handling and conversion utilities
• Map Data: Geographic data processing helpers

☁️ Cloud Integration

• AWS S3: Full support for Amazon S3 operations
• FTP: Traditional FTP server integration
• Configurable: Easy configuration for different storage providers

Installation

Install via NuGet Package Manager:

Or via Package Manager Console:

Requirements

• .NET 8.0 or higher
• Dependencies are automatically installed via NuGet

Configuration

Application Settings Structure

Add the following configuration to your appsettings.json:

Configuration Parameters

Storage Settings

File Upload Validation Settings

AWS S3 Settings

FTP Settings

SMS Settings

SMS Success Criteria

SMS Error Criteria

Configuration Examples

Basic File Upload Configuration

Restricted File Types Configuration

This configuration:

• Allows only PDF and image files
• Sets image files to max 5 MB
• Sets PDF files to max 10 MB
• Limits to 5 files per request

Using AWS S3 Storage

Using FTP Storage

SMS with JSON Response

Expected API response:

SMS with String Response

Expected API response: "SUCCESS: Message delivered"

Usage Scenarios

File Upload Operations

The library provides comprehensive file upload validation and management:

Upload validation: Files are automatically validated against configured size limits, allowed extensions, and extension-specific restrictions before upload

Multiple input formats: Supports both multipart form file uploads and Base64 encoded file content

Automatic format detection: The library can detect file formats from their binary signatures (magic numbers) for PDF, PNG, JPG, GIF, ZIP, BMP, and DOCX files

Size calculation: Automatically calculates file sizes for both FormFile and Base64Content inputs

Detailed error messages: Provides user-friendly error messages with actual file sizes in human-readable format (KB, MB, GB)

Batch validation: Validates multiple files in a single request, checking both individual file sizes and total upload size

File Validation Features

The CojectFile class provides automatic validation with the following checks:

1. Content Validation: Ensures either FormFile or Base64Content is provided (but not both)
2. Base64 Validation: Validates Base64 string format and structure
3. Size Validation: Checks file size against global and extension-specific limits
4. Extension Validation: Verifies file extensions against allowed list
5. Format Detection: Automatically detects file format from binary content
6. Total Size Validation: Validates total size when uploading multiple files

Storage Operations

Upload a file: Files are automatically routed to AWS S3, FTP, or local storage based on configuration

Download a file: Retrieve files from the configured storage provider

Generate shared link: Create temporary links with automatic expiry based on SharedLinkExpiryMinutes

Delete a file: Remove files from the configured storage backend

SMS Operations

Send OTP: The library uses the OTPMessage template to format one-time passwords

Send notifications: Send SMS messages through the configured provider

Custom parameters: The library maps your provider's parameter names using the configuration settings

Response validation: Automatically validates success/failure based on SuccessCriteria and ErrorCriteria

Email Operations

Send emails: SMTP integration with attachment support

Generate signatures: Professional email signature generation

HTML/Plain text: Support for both formats with template support

Encryption & Security

Encrypt data: Uses the configured EXPIRY_IV_KEY for secure encryption

Generate tokens: JWT token generation with configurable expiry

Shared links: Time-based security for temporary file access

File upload security: Prevents malicious uploads through extension and size restrictions

Validation Error Codes

The library returns standardized error codes for different validation scenarios:

Example Error Responses

File size exceeds limit:

Invalid file extension:

Too many files:

Extension-specific limit exceeded:

Recommended Size Limits by File Type

Project Structure

Dependencies

This package includes the following key dependencies:

• AWSSDK.S3 (v3.7.406.2) - Amazon S3 integration
• MailKit (v4.8.0) - Email operations
• MimeKit (v4.8.0) - MIME message handling
• Newtonsoft.Json (v13.0.3) - JSON serialization
• System.IdentityModel.Tokens.Jwt (v8.2.1) - JWT token handling
• ZXing.Net.Mobile (v2.4.1) - Barcode generation
• System.Drawing.Common (v9.0.0) - Image processing
• System.Data.SQLite (v1.0.119) - Database operations
• Microsoft.AspNetCore.Mvc (v2.2.0) - MVC framework support
• Coject.Core.Controller - Core controller functionality
• Coject.Core.Model - Data models

Best Practices

Security

1. Never hardcode credentials: Always use configuration files or environment variables
2. Secure configuration: Encrypt sensitive sections in production using .NET configuration encryption
3. IV Key rotation: Regularly rotate the EXPIRY_IV_KEY for enhanced security
4. Shared link expiry: Set appropriate SharedLinkExpiryMinutes based on your security requirements
5. File extension restrictions: Always define AllowedFileExtensions to prevent malicious file uploads
6. Validate file content: The library validates file content against declared extensions using magic numbers

Storage Configuration

1. Choose the right provider: AWS S3 for scalability, FTP for legacy systems, Local for development
2. Test connectivity: Verify storage provider credentials before deployment
3. Backup strategy: Implement proper backup procedures for your chosen storage type
4. Size limits: Consider storage provider limits (AWS S3 max single upload: 5GB, FTP varies by server)

File Upload Configuration

1. Set appropriate limits: Configure MaxUploadSizeBytes based on your application needs and server capacity
2. Use extension-specific limits: Define different size limits for different file types in FileSizeLimitsByExtension
3. Limit file count: Set MaxFilesPerRequest to prevent abuse and server overload
4. Whitelist extensions: Always specify AllowedFileExtensions for security
5. Monitor uploads: Log large upload attempts and validation failures
6. Test limits: Verify that Kestrel/IIS limits match your configuration settings

SMS Configuration

1. Provider compatibility: Ensure parameter names match your SMS gateway's API
2. Response validation: Test both success and error scenarios with your provider
3. URL encoding: Enable UrlEncodeParameters if your provider requires encoded values
4. Timeout settings: Adjust TimeoutSeconds based on provider response times
5. Message templates: Customize OTPMessage to match your application's branding

Performance

1. Async operations: The library uses async methods for all I/O operations
2. Connection pooling: Reuse connections when possible
3. Early validation: Files are validated before upload to save bandwidth and storage operations
4. Error handling: Implement proper try-catch blocks for network operations
5. Resource disposal: Ensure proper disposal of streams and connections
6. Caching: The helper caches configuration settings to avoid repeated reads

Troubleshooting

File Upload Issues

"Request size exceeds maximum allowed size"

• Check MaxUploadSizeBytes in appsettings.json
• Verify Kestrel/IIS MaxRequestBodySize matches configuration
• Ensure FormOptions.MultipartBodyLengthLimit is set correctly in Program.cs

"File extension not allowed"

• Add the extension to AllowedFileExtensions array
• Ensure extensions include the dot prefix (e.g., ".pdf" not "pdf")
• Check if extensions are case-sensitive in your configuration

"File size exceeds maximum for extension"

• Review FileSizeLimitsByExtension settings
• Ensure extension-specific limits are in bytes
• Verify the extension key matches exactly (including case)

"Validation failed: Base64Content is not valid"

• Ensure Base64 string is properly formatted
• Check if data URI prefix is included (e.g., "data:image/png;base64,...")
• Verify no whitespace or line breaks in Base64 string

"Total upload size exceeds limit"

• Reduce number of files per request
• Check combined size of all files against MaxUploadSizeBytes
• Consider implementing chunked uploads for large batches

Storage Issues

AWS S3 Connection Fails

• Verify Key and SecretKey are correct
• Ensure bucket exists and has proper permissions
• Check IAM policies for S3 access
• Verify bucket region matches configuration

FTP Connection Fails

• Verify server URL includes protocol (ftp:// or ftps://)
• Check username and password
• Ensure firewall allows FTP connections (typically port 21)
• Test passive vs active FTP mode

SMS Issues

Messages Not Sending

• Verify BaseUrl and SendPath are correct
• Check SMS provider credentials
• Ensure parameter names match provider's API
• Test API endpoint with provider's documentation

Success/Error Not Detected

• Review provider's response format
• Adjust SuccessCriteria.Type to match response (json/string)
• Verify property names and values are correct
• Check for case sensitivity in success/error values

Shared Link Issues

Links Expire Too Quickly

• Increase SharedLinkExpiryMinutes value
• Check server time synchronization
• Verify timezone settings

Encryption Errors

• Ensure EXPIRY_IV_KEY is valid Base64 string (16, 24, or 32 bytes when decoded)
• Verify key hasn't been modified or corrupted
• Check for whitespace in configuration value

Configuration Issues

Settings Not Loading

• Verify JSON syntax in appsettings.json
• Check for missing commas or brackets
• Ensure configuration section name matches exactly: "AttachmentSettings"
• Verify configuration is being read in Program.cs

Validation Not Working

• Ensure CojectFileControllerHelper is properly injected
• Verify ValidateFileUpload() is called before upload
• Check that settings are not null in helper class
• Review logs for validation error details

Versioning

This package follows Semantic Versioning (SemVer). Current version: 1.0.36

Support

For issues, feature requests, or contributions, please contact the development team at Akwad Arabia.

License

Copyright © Akwad Al-Arabia 2024. All rights reserved.

See LICENSE.txt for detailed license information.

Authors

Developed and maintained by Akwad Arabia

Part of the Coject Core ecosystem