@progalaxyelabs/stonescriptphp-files 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProGalaxy eLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @progalaxyelabs/stonescriptphp-files
+
+Shared file server for ProGalaxy E-Labs platforms — Azure Blob Storage + JWT auth
+
+## Installation
+
+```bash
+npm install express @progalaxyelabs/stonescriptphp-files
+```
+
+## Quick Start
+
+```javascript
+import { createFilesServer } from '@progalaxyelabs/stonescriptphp-files';
+
+// Zero-config setup (uses environment variables)
+createFilesServer().listen();
+```
+
+## Environment Variables
+
+```bash
+AZURE_STORAGE_CONNECTION_STRING=your_connection_string
+AZURE_CONTAINER_NAME=platform-files  # optional, defaults to 'platform-files'
+JWT_PUBLIC_KEY=your_jwt_public_key
+PORT=3000  # optional, defaults to 3000
+```
+
+## Advanced Configuration
+
+```javascript
+import { createFilesServer } from '@progalaxyelabs/stonescriptphp-files';
+
+const server = createFilesServer({
+  port: 3000,
+  containerName: 'my-files',
+  azureConnectionString: 'your_connection_string',
+  jwtPublicKey: 'your_public_key',
+  maxFileSize: 100 * 1024 * 1024,  // 100MB
+  corsOrigins: '*'  // or ['https://example.com']
+});
+
+server.listen();
+```
+
+## API Endpoints
+
+### POST /upload
+Upload a file (requires JWT authentication)
+
+**Request:** multipart/form-data with `file` field
+**Response:**
+```json
+{
+  "success": true,
+  "file": {
+    "id": "uuid-here",
+    "name": "filename.pdf",
+    "contentType": "application/pdf",
+    "size": 12345,
+    "uploadedAt": "2025-02-07T12:00:00.000Z"
+  }
+}
+```
+
+### GET /files/:id
+Download a file (requires JWT authentication, validates ownership)
+
+### GET /files
+List all files for authenticated user
+
+### DELETE /files/:id
+Delete a file (requires JWT authentication, validates ownership)
+
+### GET /health
+Health check endpoint (no authentication required)
+
+## Composable Usage
+
+```javascript
+import express from 'express';
+import {
+  AzureStorageClient,
+  createAuthMiddleware,
+  createUploadRouter,
+  createDownloadRouter
+} from '@progalaxyelabs/stonescriptphp-files';
+
+const app = express();
+const storage = new AzureStorageClient(connectionString, containerName);
+const authenticate = createAuthMiddleware(publicKey);
+
+await storage.initialize();
+
+app.use(authenticate, createUploadRouter(storage));
+app.use(authenticate, createDownloadRouter(storage));
+
+app.listen(3000);
+```
+
+## Features
+
+- ✅ Azure Blob Storage integration
+- ✅ JWT Bearer token authentication (RS256/ES256/HS256)
+- ✅ File ownership validation
+- ✅ Streaming uploads and downloads
+- ✅ Configurable file size limits
+- ✅ CORS support
+- ✅ Graceful shutdown handling
+- ✅ Health check endpoint
+- ✅ ESM module support
+
+## Requirements
+
+- Node.js >=24.0.0
+- Express ^5.0.0 (peer dependency)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@progalaxyelabs/stonescriptphp-files",
+  "version": "1.0.0",
+  "description": "Shared file server for ProGalaxy E-Labs platforms — Azure Blob Storage + JWT auth",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "dependencies": {
+    "@azure/storage-blob": "^12.24.0",
+    "multer": "^1.4.5-lts.1",
+    "jsonwebtoken": "^9.0.2",
+    "cors": "^2.8.5",
+    "uuid": "^11.0.5"
+  },
+  "keywords": [
+    "azure",
+    "blob-storage",
+    "file-upload",
+    "jwt",
+    "express"
+  ],
+  "author": "ProGalaxy E-Labs <info@progalaxyelabs.com> (https://www.progalaxyelabs.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/progalaxyelabs/stonescriptphp-files.git"
+  },
+  "homepage": "https://github.com/progalaxyelabs/stonescriptphp-files#readme",
+  "bugs": {
+    "url": "https://github.com/progalaxyelabs/stonescriptphp-files/issues"
+  }
+}

package/src/auth.js

@@ -0,0 +1,103 @@
+import jwt from 'jsonwebtoken';
+
+/**
+ * JWT validation middleware factory
+ * Creates a middleware that validates JWT tokens and extracts user_id for authorization
+ *
+ * @param {string} publicKey - JWT public key for token verification (RS256/ES256/HS256)
+ * @returns {Function} Express middleware function
+ */
+export function createAuthMiddleware(publicKey) {
+  if (!publicKey) {
+    throw new Error('JWT public key is required');
+  }
+
+  return function authenticateJWT(req, res, next) {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Missing or invalid authorization header'
+      });
+    }
+
+    const token = authHeader.substring(7); // Remove 'Bearer ' prefix
+
+    try {
+      // Verify token with public key
+      const decoded = jwt.verify(token, publicKey, {
+        algorithms: ['RS256', 'ES256', 'HS256']
+      });
+
+      // Extract user_id from token
+      // Common JWT claims: sub, user_id, userId, id
+      const userId = decoded.sub || decoded.user_id || decoded.userId || decoded.id;
+
+      if (!userId) {
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Token missing user identifier'
+        });
+      }
+
+      // Attach user info to request
+      req.user = {
+        id: userId,
+        email: decoded.email,
+        roles: decoded.roles || [],
+        ...decoded
+      };
+
+      next();
+    } catch (error) {
+      console.error('JWT validation error:', error.message);
+
+      if (error.name === 'TokenExpiredError') {
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Token expired'
+        });
+      }
+
+      if (error.name === 'JsonWebTokenError') {
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Invalid token'
+        });
+      }
+
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Token validation failed'
+      });
+    }
+  };
+}
+
+/**
+ * Optional: Role-based authorization middleware factory
+ * Use after authenticateJWT to check for specific roles
+ */
+export function requireRole(...allowedRoles) {
+  return (req, res, next) => {
+    if (!req.user) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Authentication required'
+      });
+    }
+
+    const userRoles = req.user.roles || [];
+    const hasRole = allowedRoles.some(role => userRoles.includes(role));
+
+    if (!hasRole) {
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: 'Insufficient permissions'
+      });
+    }
+
+    next();
+  };
+}

package/src/azure-storage.js

@@ -0,0 +1,200 @@
+import { BlobServiceClient } from '@azure/storage-blob';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * Azure Blob Storage operations
+ * Handles upload, download, list, and delete operations
+ */
+export class AzureStorageClient {
+  constructor(connectionString, containerName = 'platform-files') {
+    if (!connectionString) {
+      throw new Error('Azure Storage connection string is required');
+    }
+
+    this.connectionString = connectionString;
+    this.containerName = containerName;
+    this.blobServiceClient = null;
+    this.containerClient = null;
+  }
+
+  /**
+   * Initialize Azure Blob Storage client
+   */
+  async initialize() {
+    try {
+      // Create BlobServiceClient
+      this.blobServiceClient = BlobServiceClient.fromConnectionString(this.connectionString);
+
+      // Get container client
+      this.containerClient = this.blobServiceClient.getContainerClient(this.containerName);
+
+      // Create container if it doesn't exist
+      await this.containerClient.createIfNotExists({
+        access: 'private' // CRITICAL: No public access
+      });
+
+      console.log(`Azure Blob Storage initialized: container=${this.containerName}`);
+    } catch (error) {
+      console.error('Failed to initialize Azure Blob Storage:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Upload file to Azure Blob Storage
+   * @param {string} userId - User ID (for namespacing)
+   * @param {Buffer} fileBuffer - File content
+   * @param {string} originalFilename - Original filename
+   * @param {string} contentType - MIME type
+   * @returns {Object} File metadata
+   */
+  async uploadFile(userId, fileBuffer, originalFilename, contentType) {
+    if (!this.containerClient) {
+      throw new Error('Azure Storage not initialized');
+    }
+
+    // Generate unique blob name: {user_id}/{uuid}.{ext}
+    const fileId = uuidv4();
+    const extension = originalFilename.split('.').pop();
+    const blobName = `${userId}/${fileId}.${extension}`;
+
+    const blockBlobClient = this.containerClient.getBlockBlobClient(blobName);
+
+    // Upload with metadata
+    await blockBlobClient.upload(fileBuffer, fileBuffer.length, {
+      blobHTTPHeaders: {
+        blobContentType: contentType
+      },
+      metadata: {
+        user_id: userId,
+        original_filename: originalFilename,
+        content_type: contentType,
+        uploaded_at: new Date().toISOString(),
+        file_id: fileId
+      }
+    });
+
+    return {
+      fileId,
+      blobName,
+      userId,
+      originalFilename,
+      contentType,
+      size: fileBuffer.length,
+      uploadedAt: new Date().toISOString()
+    };
+  }
+
+  /**
+   * Download file from Azure Blob Storage
+   * @param {string} fileId - File ID (UUID)
+   * @param {string} userId - User ID (for authorization)
+   * @returns {Object} { stream, metadata }
+   */
+  async downloadFile(fileId, userId) {
+    if (!this.containerClient) {
+      throw new Error('Azure Storage not initialized');
+    }
+
+    // List blobs with file_id metadata to find the blob
+    const blobs = this.containerClient.listBlobsFlat({
+      prefix: `${userId}/`,
+      includeMetadata: true
+    });
+
+    for await (const blob of blobs) {
+      if (blob.metadata && blob.metadata.file_id === fileId) {
+        const blockBlobClient = this.containerClient.getBlockBlobClient(blob.name);
+
+        // Verify ownership
+        if (blob.metadata.user_id !== userId) {
+          throw new Error('Unauthorized: File belongs to different user');
+        }
+
+        // Download blob
+        const downloadResponse = await blockBlobClient.download(0);
+
+        return {
+          stream: downloadResponse.readableStreamBody,
+          metadata: {
+            fileName: blob.metadata.original_filename,
+            contentType: blob.metadata.content_type,
+            size: blob.properties.contentLength
+          }
+        };
+      }
+    }
+
+    throw new Error('File not found');
+  }
+
+  /**
+   * List user's files
+   * @param {string} userId - User ID
+   * @returns {Array} List of file metadata
+   */
+  async listFiles(userId) {
+    if (!this.containerClient) {
+      throw new Error('Azure Storage not initialized');
+    }
+
+    const files = [];
+    const blobs = this.containerClient.listBlobsFlat({
+      prefix: `${userId}/`,
+      includeMetadata: true
+    });
+
+    for await (const blob of blobs) {
+      if (blob.metadata) {
+        files.push({
+          fileId: blob.metadata.file_id,
+          fileName: blob.metadata.original_filename,
+          contentType: blob.metadata.content_type,
+          size: blob.properties.contentLength,
+          uploadedAt: blob.metadata.uploaded_at
+        });
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Delete file from Azure Blob Storage
+   * @param {string} fileId - File ID (UUID)
+   * @param {string} userId - User ID (for authorization)
+   */
+  async deleteFile(fileId, userId) {
+    if (!this.containerClient) {
+      throw new Error('Azure Storage not initialized');
+    }
+
+    // Find blob by file_id
+    const blobs = this.containerClient.listBlobsFlat({
+      prefix: `${userId}/`,
+      includeMetadata: true
+    });
+
+    for await (const blob of blobs) {
+      if (blob.metadata && blob.metadata.file_id === fileId) {
+        // Verify ownership
+        if (blob.metadata.user_id !== userId) {
+          throw new Error('Unauthorized: File belongs to different user');
+        }
+
+        const blockBlobClient = this.containerClient.getBlockBlobClient(blob.name);
+        await blockBlobClient.delete();
+        return;
+      }
+    }
+
+    throw new Error('File not found');
+  }
+
+  /**
+   * Get container client (for advanced operations)
+   */
+  getContainerClient() {
+    return this.containerClient;
+  }
+}

package/src/index.js

@@ -0,0 +1,114 @@
+import express from 'express';
+import cors from 'cors';
+import { AzureStorageClient } from './azure-storage.js';
+import { createAuthMiddleware } from './auth.js';
+import { createUploadRouter } from './routes/upload.js';
+import { createDownloadRouter } from './routes/download.js';
+import { createListRouter } from './routes/list.js';
+import { createDeleteRouter } from './routes/delete.js';
+import { createHealthRouter } from './routes/health.js';
+
+/**
+ * Create a configured files server
+ * @param {Object} config - Configuration options
+ * @param {number} config.port - Server port (default: process.env.PORT || 3000)
+ * @param {string} config.containerName - Azure container name (default: process.env.AZURE_CONTAINER_NAME || 'platform-files')
+ * @param {string} config.azureConnectionString - Azure storage connection string (default: process.env.AZURE_STORAGE_CONNECTION_STRING)
+ * @param {string} config.jwtPublicKey - JWT public key for auth (default: process.env.JWT_PUBLIC_KEY)
+ * @param {number} config.maxFileSize - Max file size in bytes (default: 100MB)
+ * @param {string|string[]} config.corsOrigins - CORS allowed origins (default: '*')
+ * @returns {Object} Server object with app, storage, and listen() method
+ */
+export function createFilesServer(config = {}) {
+  const port = config.port || process.env.PORT || 3000;
+  const containerName = config.containerName || process.env.AZURE_CONTAINER_NAME || 'platform-files';
+  const connectionString = config.azureConnectionString || process.env.AZURE_STORAGE_CONNECTION_STRING;
+  const jwtPublicKey = config.jwtPublicKey || process.env.JWT_PUBLIC_KEY;
+  const maxFileSize = config.maxFileSize || 100 * 1024 * 1024;
+  const corsOrigins = config.corsOrigins || '*';
+
+  // Create storage client
+  const storage = new AzureStorageClient(connectionString, containerName);
+
+  // Create auth middleware
+  const authenticate = createAuthMiddleware(jwtPublicKey);
+
+  // Create Express app
+  const app = express();
+
+  // Configure CORS
+  app.use(cors({ origin: corsOrigins }));
+
+  // Body parsing middleware
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: true }));
+
+  // Request logging
+  app.use((req, res, next) => {
+    console.log(`${new Date().toISOString()} ${req.method} ${req.url}`);
+    next();
+  });
+
+  // Routes
+  app.use(createHealthRouter());
+  app.use(authenticate, createUploadRouter(storage, maxFileSize));
+  app.use(authenticate, createDownloadRouter(storage));
+  app.use(authenticate, createListRouter(storage));
+  app.use(authenticate, createDeleteRouter(storage));
+
+  // 404 handler
+  app.use((req, res) => {
+    res.status(404).json({
+      error: 'Not Found',
+      message: 'The requested endpoint does not exist'
+    });
+  });
+
+  // Error handler
+  app.use((err, req, res, next) => {
+    console.error('Unhandled error:', err);
+    res.status(500).json({
+      error: 'Internal Server Error',
+      message: 'An unexpected error occurred'
+    });
+  });
+
+  // Server object with listen method
+  const server = {
+    app,
+    storage,
+    listen: () => {
+      return storage.initialize().then(() => {
+        const httpServer = app.listen(port, () => {
+          console.log(`Files server listening on port ${port}`);
+          console.log(`Health check: http://localhost:${port}/health`);
+        });
+
+        // Graceful shutdown
+        const shutdown = () => {
+          console.log('Shutting down gracefully...');
+          httpServer.close(() => {
+            console.log('Server closed');
+            process.exit(0);
+          });
+        };
+
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+
+        return httpServer;
+      });
+    }
+  };
+
+  return server;
+}
+
+// Named exports for advanced/composable usage
+export { AzureStorageClient } from './azure-storage.js';
+export { createAuthMiddleware } from './auth.js';
+export { createUploadRouter } from './routes/upload.js';
+export { createDownloadRouter } from './routes/download.js';
+export { createListRouter } from './routes/list.js';
+export { createDeleteRouter } from './routes/delete.js';
+export { createHealthRouter } from './routes/health.js';

package/src/routes/delete.js

@@ -0,0 +1,63 @@
+import express from 'express';
+
+/**
+ * Delete file router factory
+ * @param {AzureStorageClient} storage - Azure storage client instance
+ * @returns {express.Router} Express router for delete endpoint
+ */
+export function createDeleteRouter(storage) {
+  const router = express.Router();
+
+  /**
+   * DELETE /files/:id
+   * Delete file from Azure Blob Storage
+   * Requires: JWT authentication (applied by parent app)
+   * Validates: User owns the file
+   */
+  router.delete('/files/:id', async (req, res) => {
+    try {
+      const fileId = req.params.id;
+      const userId = req.user.id;
+
+      // Validate file ID format (UUID)
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (!uuidRegex.test(fileId)) {
+        return res.status(400).json({
+          error: 'Bad Request',
+          message: 'Invalid file ID format'
+        });
+      }
+
+      // Delete file from Azure (validates ownership)
+      await storage.deleteFile(fileId, userId);
+
+      res.status(200).json({
+        success: true,
+        message: 'File deleted successfully'
+      });
+    } catch (error) {
+      console.error('Delete error:', error);
+
+      if (error.message === 'File not found') {
+        return res.status(404).json({
+          error: 'Not Found',
+          message: 'File not found'
+        });
+      }
+
+      if (error.message.startsWith('Unauthorized:')) {
+        return res.status(403).json({
+          error: 'Forbidden',
+          message: error.message
+        });
+      }
+
+      res.status(500).json({
+        error: 'Internal Server Error',
+        message: 'Failed to delete file'
+      });
+    }
+  });
+
+  return router;
+}

package/src/routes/download.js

@@ -0,0 +1,77 @@
+import express from 'express';
+
+/**
+ * Download router factory
+ * @param {AzureStorageClient} storage - Azure storage client instance
+ * @returns {express.Router} Express router for download endpoint
+ */
+export function createDownloadRouter(storage) {
+  const router = express.Router();
+
+  /**
+   * GET /files/:id
+   * Download file from Azure Blob Storage
+   * Requires: JWT authentication (applied by parent app)
+   * Validates: User owns the file
+   */
+  router.get('/files/:id', async (req, res) => {
+    try {
+      const fileId = req.params.id;
+      const userId = req.user.id;
+
+      // Validate file ID format (UUID)
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (!uuidRegex.test(fileId)) {
+        return res.status(400).json({
+          error: 'Bad Request',
+          message: 'Invalid file ID format'
+        });
+      }
+
+      // Download file from Azure (validates ownership)
+      const { stream, metadata } = await storage.downloadFile(fileId, userId);
+
+      // Set response headers
+      res.setHeader('Content-Type', metadata.contentType);
+      res.setHeader('Content-Length', metadata.size);
+      res.setHeader('Content-Disposition', `attachment; filename="${metadata.fileName}"`);
+
+      // Stream file to response
+      stream.pipe(res);
+
+      // Handle stream errors
+      stream.on('error', (error) => {
+        console.error('Stream error:', error);
+        if (!res.headersSent) {
+          res.status(500).json({
+            error: 'Internal Server Error',
+            message: 'Failed to stream file'
+          });
+        }
+      });
+    } catch (error) {
+      console.error('Download error:', error);
+
+      if (error.message === 'File not found') {
+        return res.status(404).json({
+          error: 'Not Found',
+          message: 'File not found'
+        });
+      }
+
+      if (error.message.startsWith('Unauthorized:')) {
+        return res.status(403).json({
+          error: 'Forbidden',
+          message: error.message
+        });
+      }
+
+      res.status(500).json({
+        error: 'Internal Server Error',
+        message: 'Failed to download file'
+      });
+    }
+  });
+
+  return router;
+}

package/src/routes/health.js

@@ -0,0 +1,23 @@
+import express from 'express';
+
+/**
+ * Health check router factory
+ * @returns {express.Router} Express router for health endpoint
+ */
+export function createHealthRouter() {
+  const router = express.Router();
+
+  /**
+   * GET /health
+   * Public health check endpoint (no authentication required)
+   */
+  router.get('/health', (req, res) => {
+    res.status(200).json({
+      status: 'healthy',
+      service: 'files-service',
+      timestamp: new Date().toISOString()
+    });
+  });
+
+  return router;
+}

package/src/routes/list.js

@@ -0,0 +1,40 @@
+import express from 'express';
+
+/**
+ * List files router factory
+ * @param {AzureStorageClient} storage - Azure storage client instance
+ * @returns {express.Router} Express router for list endpoint
+ */
+export function createListRouter(storage) {
+  const router = express.Router();
+
+  /**
+   * GET /files
+   * List user's files from Azure Blob Storage
+   * Requires: JWT authentication (applied by parent app)
+   * Returns: Array of file metadata for current user
+   */
+  router.get('/files', async (req, res) => {
+    try {
+      const userId = req.user.id;
+
+      // List files for current user
+      const files = await storage.listFiles(userId);
+
+      res.status(200).json({
+        success: true,
+        count: files.length,
+        files: files
+      });
+    } catch (error) {
+      console.error('List files error:', error);
+
+      res.status(500).json({
+        error: 'Internal Server Error',
+        message: 'Failed to list files'
+      });
+    }
+  });
+
+  return router;
+}

package/src/routes/upload.js

@@ -0,0 +1,78 @@
+import express from 'express';
+import multer from 'multer';
+
+/**
+ * Upload router factory
+ * @param {AzureStorageClient} storage - Azure storage client instance
+ * @param {number} maxFileSize - Maximum file size in bytes (default: 100MB)
+ * @returns {express.Router} Express router for upload endpoint
+ */
+export function createUploadRouter(storage, maxFileSize = 100 * 1024 * 1024) {
+  const router = express.Router();
+
+  // Configure multer for memory storage (files stored in RAM before Azure upload)
+  const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: {
+      fileSize: maxFileSize,
+      files: 1 // Single file upload
+    },
+    fileFilter: (req, file, cb) => {
+      // Optional: Add file type validation here
+      // For now, accept all file types
+      cb(null, true);
+    }
+  });
+
+  /**
+   * POST /upload
+   * Upload file to Azure Blob Storage
+   * Requires: JWT authentication (applied by parent app)
+   * Body: multipart/form-data with 'file' field
+   */
+  router.post('/upload', upload.single('file'), async (req, res) => {
+    try {
+      // Validate file was uploaded
+      if (!req.file) {
+        return res.status(400).json({
+          error: 'Bad Request',
+          message: 'No file uploaded'
+        });
+      }
+
+      const userId = req.user.id;
+      const { buffer, originalname, mimetype } = req.file;
+
+      // Upload to Azure Blob Storage
+      const fileMetadata = await storage.uploadFile(userId, buffer, originalname, mimetype);
+
+      // Return success response
+      res.status(201).json({
+        success: true,
+        file: {
+          id: fileMetadata.fileId,
+          name: fileMetadata.originalFilename,
+          contentType: fileMetadata.contentType,
+          size: fileMetadata.size,
+          uploadedAt: fileMetadata.uploadedAt
+        }
+      });
+    } catch (error) {
+      console.error('Upload error:', error);
+
+      if (error.code === 'LIMIT_FILE_SIZE') {
+        return res.status(413).json({
+          error: 'Payload Too Large',
+          message: `File size exceeds ${Math.round(maxFileSize / 1024 / 1024)}MB limit`
+        });
+      }
+
+      res.status(500).json({
+        error: 'Internal Server Error',
+        message: 'Failed to upload file'
+      });
+    }
+  });
+
+  return router;
+}