Skip to main content

Azure Blob Upload Module

This module provides secure file upload and download functionality using Azure Blob Storage with optional encryption support.

Features​

  • Secure Upload: POST endpoint with authentication required
  • Secure Download: GET endpoint with authentication required
  • File Type Validation: Only images and documents allowed
  • Container Name Validation: Only predefined container names allowed
  • Optional Encryption: Files can be encrypted before storage
  • Metadata Tracking: All uploads are tracked in the database
  • Raw Data Return: Download endpoint returns raw file data, not links

Supported File Types​

Images​

  • JPEG, JPG, PNG, GIF, WebP, BMP, TIFF

Documents​

  • PDF, Word (.doc, .docx), Excel (.xls, .xlsx), PowerPoint (.ppt, .pptx)
  • Plain text (.txt), CSV
  • RTF, XML, JSON

Allowed Container Names​

The following container names are allowed for file uploads:

  • uploads - General uploads (default)
  • documents - Document files
  • images - Image files
  • temp - Temporary files
  • archived - Archived files

Note: Only these predefined container names are accepted. Any other container name will result in a validation error.

Environment Variables​

Add the following environment variables to your .env file:

AZURE_STORAGE_CONNECTION_STRING=your_azure_storage_connection_string
AZURE_STORAGE_ENCRYPTION_KEY=your_encryption_key_for_secure_files

Note: The AZURE_STORAGE_ENCRYPTION_KEY environment variable is required when uploading encrypted files. If this variable is not set, encrypted file uploads will fail with an error.

API Endpoints​

POST /azure-blob/upload​

Upload a file to Azure Blob Storage.

Authentication: Required (Bearer token)

Content-Type: multipart/form-data

Request Body:

  • file: The file to upload (binary)

  • originalFilename: Original filename (string)

  • contentType: MIME type of the file (string)

  • fileSize: File size in bytes (number)

  • isEncrypted: Whether to encrypt the file (boolean, optional)

  • businessLocationId: Business location ID (string, optional)

  • practiceId: Practice ID (string, optional)

  • containerName: Azure blob container name (string, optional, defaults to "uploads")

    • Allowed values: uploads, documents, images, temp, archived

Response: BlobResponseDto

GET /azure-blob/download/:id​

Download a file from Azure Blob Storage.

Authentication: Required (Bearer token)

Parameters:

  • id: Blob entry ID (number)

Response: Raw file data with appropriate headers

GET /azure-blob/metadata/:id​

Get metadata for a blob entry.

Authentication: Required (Bearer token)

Parameters:

  • id: Blob entry ID (number)

Response: BlobResponseDto

DELETE /azure-blob/:id​

Delete a blob from Azure Blob Storage.

Authentication: Required (Bearer token)

Parameters:

  • id: Blob entry ID (number)

Response: { message: string }

Database Schema​

The module creates a blob_entries table with the following structure:

CREATE TABLE blob_entries (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  blob_name VARCHAR NOT NULL,
  container_name VARCHAR NOT NULL,
  original_filename VARCHAR NOT NULL,
  content_type VARCHAR NOT NULL,
  file_size BIGINT NOT NULL,
  is_encrypted BOOLEAN NOT NULL DEFAULT FALSE,
  encryption_key_id VARCHAR,
  uploaded_by VARCHAR NOT NULL,
  business_location_id VARCHAR,
  practice_id VARCHAR,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

Encryption​

When isEncrypted is set to true:

  1. The file is encrypted using AES-256-GCM before upload
  2. An encryption key ID is generated or provided
  3. The encrypted data is stored in Azure Blob Storage
  4. When downloading, the file is automatically decrypted

Usage Examples​

Upload a regular file​

curl -X POST /azure-blob/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F "originalFilename=document.pdf" \
  -F "contentType=application/pdf" \
  -F "fileSize=1024000"

Upload an encrypted file​

curl -X POST /azure-blob/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@sensitive.pdf" \
  -F "originalFilename=sensitive.pdf" \
  -F "contentType=application/pdf" \
  -F "fileSize=2048000" \
  -F "isEncrypted=true"

Note: When isEncrypted=true, the system will automatically generate an encryption key ID and use the AZURE_STORAGE_ENCRYPTION_KEY environment variable for encryption.

Download a file​

curl -X GET /azure-blob/download/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output downloaded_file.pdf

Delete a file​

curl -X DELETE /azure-blob/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Security Considerations​

  1. Authentication: All endpoints require valid JWT tokens
  2. File Type Validation: Only allowed file types can be uploaded
  3. Encryption: Sensitive files can be encrypted before storage
  4. Access Control: Files are associated with business locations and practices
  5. Audit Trail: All uploads are tracked with user information

Error Handling​

The module handles various error scenarios:

  • Invalid File Type: Returns 400 Bad Request
  • Missing File: Returns 400 Bad Request
  • Blob Not Found: Returns 404 Not Found
  • Authentication Failure: Returns 401 Unauthorized
  • Encryption Errors: Returns 400 Bad Request with details