@progalaxyelabs/stonescriptphp-files 2.0.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progalaxyelabs/stonescriptphp-files",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Zero-config Express file server with Azure Blob Storage and JWT authentication",
   "type": "module",
   "main": "src/index.js",

package/src/authorization.js

@@ -0,0 +1,124 @@
+/**
+ * Optional authorization middleware for stonescriptphp-files.
+ *
+ * When AUTHORIZATION_URL is configured, calls the platform API to check
+ * if the current user is allowed to perform the file operation.
+ * The API acts as an authorization oracle — it knows about business entities
+ * and role hierarchies. The files service stays generic.
+ *
+ * When AUTHORIZATION_URL is NOT set, this is a no-op pass-through.
+ */
+
+/**
+ * Create authorization middleware
+ * @param {string|null} authorizationUrl - URL to call for auth checks (e.g., "http://api:9100/files/authorize")
+ * @param {number} timeout - Request timeout in ms (default: 3000)
+ * @returns {Function} Express middleware
+ */
+export function createAuthorizationMiddleware(authorizationUrl, timeout = 3000) {
+  if (!authorizationUrl) {
+    // No authorization configured — pass through (backwards compat)
+    return (req, res, next) => {
+      req.fileScope = 'user';
+      next();
+    };
+  }
+
+  console.log(`Authorization middleware enabled: ${authorizationUrl}`);
+
+  return async (req, res, next) => {
+    try {
+      // Determine action from HTTP method + path
+      let action;
+      if (req.method === 'POST' && req.path === '/upload') {
+        action = 'upload';
+      } else if (req.method === 'GET' && req.path.startsWith('/files/')) {
+        action = 'download';
+      } else if (req.method === 'DELETE' && req.path.startsWith('/files/')) {
+        action = 'delete';
+      } else {
+        // Not a file operation route (e.g., /health, /list) — pass through
+        req.fileScope = 'user';
+        return next();
+      }
+
+      // Build authorization request body
+      const body = { action };
+
+      if ((action === 'download' || action === 'delete') && req.params.id) {
+        body.file_id = req.params.id;
+      }
+
+      if (action === 'upload') {
+        body.resource_type = req.body?.resource_type || null;
+        body.resource_id = req.body?.resource_id ? parseInt(req.body.resource_id) : null;
+      }
+
+      // Forward the user's JWT token
+      const authHeader = req.headers.authorization;
+
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      const response = await fetch(authorizationUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(authHeader ? { 'Authorization': authHeader } : {})
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorRaw = await response.json().catch(() => ({}));
+        const errorBody = errorRaw.data || errorRaw;
+
+        if (response.status === 403) {
+          console.warn(`Authorization denied: user=${req.user?.id} action=${action} reason=${errorBody.reason || errorRaw.message || 'unknown'}`);
+          return res.status(403).json({
+            error: 'Forbidden',
+            message: errorBody.reason || errorRaw.message || 'Access denied'
+          });
+        }
+
+        console.error(`Authorization service error: status=${response.status} body=${JSON.stringify(errorBody)}`);
+        return res.status(503).json({
+          error: 'Service Unavailable',
+          message: 'Authorization service returned an error'
+        });
+      }
+
+      const raw = await response.json();
+      // Unwrap StoneScriptPHP {status, message, data} wrapper if present
+      const authResult = raw.data || raw;
+
+      if (!authResult.allowed) {
+        console.warn(`Authorization denied: user=${req.user?.id} action=${action} reason=${authResult.reason || 'unknown'}`);
+        return res.status(403).json({
+          error: 'Forbidden',
+          message: authResult.reason || 'Access denied'
+        });
+      }
+
+      // Set scope on request for route handlers
+      req.fileScope = authResult.scope || 'user';
+      next();
+
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        console.error(`Authorization timeout: url=${authorizationUrl} timeout=${timeout}ms`);
+      } else {
+        console.error(`Authorization error: ${error.message}`);
+      }
+
+      // Fail closed — deny access when authorization service is unavailable
+      return res.status(503).json({
+        error: 'Service Unavailable',
+        message: 'Authorization service unavailable'
+      });
+    }
+  };
+}

package/src/azure-storage.js

@@ -7,20 +7,22 @@ import { v4 as uuidv4 } from 'uuid';
  */
 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;
+    this.isConfigured = !!connectionString;
   }
 
   /**
    * Initialize Azure Blob Storage client
    */
   async initialize() {
+    if (!this.isConfigured) {
+      console.warn('⚠️  AZURE_STORAGE_CONNECTION_STRING not set — file uploads will fail');
+      return;
+    }
+
     try {
       // Create BlobServiceClient
       this.blobServiceClient = BlobServiceClient.fromConnectionString(this.connectionString);
@@ -28,10 +30,8 @@ export class AzureStorageClient {
       // 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
-      });
+      // Create container if it doesn't exist (no access property = private, no public access)
+      await this.containerClient.createIfNotExists();
 
       console.log(`Azure Blob Storage initialized: container=${this.containerName}`);
     } catch (error) {
@@ -47,17 +47,29 @@ export class AzureStorageClient {
    * @param {Buffer} fileBuffer - File content
    * @param {string} originalFilename - Original filename
    * @param {string} contentType - MIME type
+   * @param {string} scope - Storage scope: 'user' (default) or 'tenant'
    * @returns {Object} File metadata
    */
-  async uploadFile(tenantId, userId, fileBuffer, originalFilename, contentType) {
+  async uploadFile(tenantId, userId, fileBuffer, originalFilename, contentType, scope = 'user') {
+    if (!this.isConfigured) {
+      const error = new Error('Storage not configured');
+      error.statusCode = 503;
+      throw error;
+    }
+
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
-    // Generate unique blob name with tenant prefix: {tenant_id}/{user_id}/{uuid}.{ext}
+    // Generate unique blob name with scope-based prefix
     const fileId = uuidv4();
     const extension = originalFilename.split('.').pop();
-    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    let prefix;
+    if (scope === 'tenant') {
+      prefix = tenantId ? `${tenantId}/shared/` : 'shared/';
+    } else {
+      prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    }
     const blobName = `${prefix}${fileId}.${extension}`;
 
     const blockBlobClient = this.containerClient.getBlockBlobClient(blobName);
@@ -73,7 +85,8 @@ export class AzureStorageClient {
         original_filename: originalFilename,
         content_type: contentType,
         uploaded_at: new Date().toISOString(),
-        file_id: fileId
+        file_id: fileId,
+        scope: scope
       }
     });
 
@@ -94,15 +107,28 @@ export class AzureStorageClient {
    * @param {string} fileId - File ID (UUID)
    * @param {string} tenantId - Tenant ID (for multi-tenant namespacing)
    * @param {string} userId - User ID (for authorization)
+   * @param {string} scope - Storage scope: 'user' (default) or 'tenant'
    * @returns {Object} { stream, metadata }
    */
-  async downloadFile(fileId, tenantId, userId) {
+  async downloadFile(fileId, tenantId, userId, scope = 'user') {
+    if (!this.isConfigured) {
+      const error = new Error('Storage not configured');
+      error.statusCode = 503;
+      throw error;
+    }
+
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
-    // List blobs with prefix to find the blob
-    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    // Build prefix based on scope
+    let prefix;
+    if (scope === 'tenant') {
+      prefix = tenantId ? `${tenantId}/shared/` : 'shared/';
+    } else {
+      prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    }
+
     const blobs = this.containerClient.listBlobsFlat({
       prefix,
       includeMetadata: true
@@ -112,8 +138,9 @@ export class AzureStorageClient {
       if (blob.metadata && blob.metadata.file_id === fileId) {
         const blockBlobClient = this.containerClient.getBlockBlobClient(blob.name);
 
-        // Verify ownership
-        if (blob.metadata.user_id !== userId) {
+        // Verify ownership for user-scoped files only
+        // Tenant-scoped files are shared — authorization middleware already checked access
+        if (scope === 'user' && blob.metadata.user_id !== userId) {
           throw new Error('Unauthorized: File belongs to different user');
         }
 
@@ -138,15 +165,27 @@ export class AzureStorageClient {
    * List user's files
    * @param {string} tenantId - Tenant ID (for multi-tenant namespacing)
    * @param {string} userId - User ID
+   * @param {string} scope - Storage scope: 'user' (default) or 'tenant'
    * @returns {Array} List of file metadata
    */
-  async listFiles(tenantId, userId) {
+  async listFiles(tenantId, userId, scope = 'user') {
+    if (!this.isConfigured) {
+      const error = new Error('Storage not configured');
+      error.statusCode = 503;
+      throw error;
+    }
+
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
     const files = [];
-    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    let prefix;
+    if (scope === 'tenant') {
+      prefix = tenantId ? `${tenantId}/shared/` : 'shared/';
+    } else {
+      prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    }
     const blobs = this.containerClient.listBlobsFlat({
       prefix,
       includeMetadata: true
@@ -172,14 +211,27 @@ export class AzureStorageClient {
    * @param {string} fileId - File ID (UUID)
    * @param {string} tenantId - Tenant ID (for multi-tenant namespacing)
    * @param {string} userId - User ID (for authorization)
+   * @param {string} scope - Storage scope: 'user' (default) or 'tenant'
    */
-  async deleteFile(fileId, tenantId, userId) {
+  async deleteFile(fileId, tenantId, userId, scope = 'user') {
+    if (!this.isConfigured) {
+      const error = new Error('Storage not configured');
+      error.statusCode = 503;
+      throw error;
+    }
+
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
-    // Find blob by file_id
-    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    // Find blob by file_id with scope-based prefix
+    let prefix;
+    if (scope === 'tenant') {
+      prefix = tenantId ? `${tenantId}/shared/` : 'shared/';
+    } else {
+      prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    }
+
     const blobs = this.containerClient.listBlobsFlat({
       prefix,
       includeMetadata: true
@@ -187,8 +239,8 @@ export class AzureStorageClient {
 
     for await (const blob of blobs) {
       if (blob.metadata && blob.metadata.file_id === fileId) {
-        // Verify ownership
-        if (blob.metadata.user_id !== userId) {
+        // Verify ownership for user-scoped files only
+        if (scope === 'user' && blob.metadata.user_id !== userId) {
           throw new Error('Unauthorized: File belongs to different user');
         }
 

package/src/index.js

@@ -3,6 +3,7 @@ import cors from 'cors';
 import { AzureStorageClient } from './azure-storage.js';
 import { createAuthMiddleware, createJwksAuthMiddleware } from './auth.js';
 import { JwksClient } from './jwks-client.js';
+import { createAuthorizationMiddleware } from './authorization.js';
 import { createRateLimiters } from './rate-limit.js';
 import { createUploadRouter } from './routes/upload.js';
 import { createDownloadRouter } from './routes/download.js';
@@ -13,6 +14,7 @@ import { createHealthRouter } from './routes/health.js';
 /**
  * Resolve the authentication middleware based on configuration priority.
  * Priority: authServers > jwksUrl > jwtPublicKey
+ * If no auth is configured, returns a pass-through middleware that logs a warning.
  *
  * @param {Object} config - Configuration options
  * @returns {Function} Express middleware function for authentication
@@ -37,7 +39,14 @@ function resolveAuthMiddleware(config) {
     return createAuthMiddleware(jwtPublicKey);
   }
 
-  throw new Error('No authentication method configured. Set AUTH_SERVERS, JWKS_URL, or JWT_PUBLIC_KEY.');
+  // No auth configured - return pass-through middleware with warning
+  console.warn('⚠️  No authentication configured — all endpoints will fail with 503');
+  return (req, res, next) => {
+    res.status(503).json({
+      error: 'Service Unavailable',
+      message: 'Authentication not configured'
+    });
+  };
 }
 
 /**
@@ -51,6 +60,8 @@ function resolveAuthMiddleware(config) {
  * @param {string} config.jwksUrl - Single JWKS URL for key retrieval
  * @param {number} config.jwksCacheTtl - JWKS cache TTL in seconds (default: 3600)
  * @param {boolean} config.tenantScoped - Enable tenant-scoped file isolation (default: true)
+ * @param {string} config.authorizationUrl - URL for authorization checks (default: process.env.AUTHORIZATION_URL). When set, files service calls this URL before upload/download/delete.
+ * @param {number} config.authorizationTimeout - Authorization request timeout in ms (default: 3000)
  * @param {number} config.maxFileSize - Max file size in bytes (default: 100MB)
  * @param {string|string[]} config.corsOrigins - CORS allowed origins (default: '*')
  * @param {number} config.rateLimitWindowMs - Rate limit window in ms (default: 60000)
@@ -72,6 +83,11 @@ export function createFilesServer(config = {}) {
   // Resolve auth middleware based on config priority
   const authenticate = resolveAuthMiddleware(config);
 
+  // Resolve authorization middleware (optional — no-op when URL not set)
+  const authorizationUrl = config.authorizationUrl || process.env.AUTHORIZATION_URL || null;
+  const authorizationTimeout = config.authorizationTimeout || parseInt(process.env.AUTHORIZATION_TIMEOUT) || 3000;
+  const authorize = createAuthorizationMiddleware(authorizationUrl, authorizationTimeout);
+
   // Create rate limiters
   const { uploadLimiter, downloadLimiter } = createRateLimiters(config);
 
@@ -91,12 +107,12 @@ export function createFilesServer(config = {}) {
     next();
   });
 
-  // Routes with rate limiters
+  // Routes with rate limiters and optional authorization
   app.use(createHealthRouter());
-  app.use(authenticate, uploadLimiter, createUploadRouter(storage, maxFileSize));
-  app.use(authenticate, downloadLimiter, createDownloadRouter(storage));
+  app.use(authenticate, authorize, uploadLimiter, createUploadRouter(storage, maxFileSize));
+  app.use(authenticate, authorize, downloadLimiter, createDownloadRouter(storage));
   app.use(authenticate, downloadLimiter, createListRouter(storage));
-  app.use(authenticate, downloadLimiter, createDeleteRouter(storage));
+  app.use(authenticate, authorize, downloadLimiter, createDeleteRouter(storage));
 
   // 404 handler
   app.use((req, res) => {
@@ -149,6 +165,7 @@ export function createFilesServer(config = {}) {
 // Named exports for advanced/composable usage
 export { AzureStorageClient } from './azure-storage.js';
 export { createAuthMiddleware, createJwksAuthMiddleware } from './auth.js';
+export { createAuthorizationMiddleware } from './authorization.js';
 export { JwksClient } from './jwks-client.js';
 export { createRateLimiters } from './rate-limit.js';
 export { createUploadRouter } from './routes/upload.js';

package/src/routes/delete.js

@@ -19,6 +19,7 @@ export function createDeleteRouter(storage) {
       const fileId = req.params.id;
       const userId = req.user.id;
       const tenantId = req.user.tenantId;
+      const scope = req.fileScope || 'user';
 
       // 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;
@@ -29,8 +30,8 @@ export function createDeleteRouter(storage) {
         });
       }
 
-      // Delete file from Azure (validates ownership)
-      await storage.deleteFile(fileId, tenantId, userId);
+      // Delete file from Azure (validates ownership for user-scoped files)
+      await storage.deleteFile(fileId, tenantId, userId, scope);
 
       res.status(200).json({
         success: true,
@@ -53,6 +54,13 @@ export function createDeleteRouter(storage) {
         });
       }
 
+      if (error.statusCode === 503) {
+        return res.status(503).json({
+          error: 'Service Unavailable',
+          message: error.message
+        });
+      }
+
       res.status(500).json({
         error: 'Internal Server Error',
         message: 'Failed to delete file'

package/src/routes/download.js

@@ -19,6 +19,7 @@ export function createDownloadRouter(storage) {
       const fileId = req.params.id;
       const userId = req.user.id;
       const tenantId = req.user.tenantId;
+      const scope = req.fileScope || 'user';
 
       // 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;
@@ -29,8 +30,8 @@ export function createDownloadRouter(storage) {
         });
       }
 
-      // Download file from Azure (validates ownership)
-      const { stream, metadata } = await storage.downloadFile(fileId, tenantId, userId);
+      // Download file from Azure (validates ownership for user-scoped files)
+      const { stream, metadata } = await storage.downloadFile(fileId, tenantId, userId, scope);
 
       // Set response headers
       res.setHeader('Content-Type', metadata.contentType);
@@ -67,6 +68,13 @@ export function createDownloadRouter(storage) {
         });
       }
 
+      if (error.statusCode === 503) {
+        return res.status(503).json({
+          error: 'Service Unavailable',
+          message: error.message
+        });
+      }
+
       res.status(500).json({
         error: 'Internal Server Error',
         message: 'Failed to download file'

package/src/routes/list.js

@@ -30,6 +30,13 @@ export function createListRouter(storage) {
     } catch (error) {
       console.error('List files error:', error);
 
+      if (error.statusCode === 503) {
+        return res.status(503).json({
+          error: 'Service Unavailable',
+          message: error.message
+        });
+      }
+
       res.status(500).json({
         error: 'Internal Server Error',
         message: 'Failed to list files'

package/src/routes/upload.js

@@ -42,10 +42,11 @@ export function createUploadRouter(storage, maxFileSize = 100 * 1024 * 1024) {
 
       const userId = req.user.id;
       const tenantId = req.user.tenantId;
+      const scope = req.fileScope || 'user';
       const { buffer, originalname, mimetype } = req.file;
 
       // Upload to Azure Blob Storage
-      const fileMetadata = await storage.uploadFile(tenantId, userId, buffer, originalname, mimetype);
+      const fileMetadata = await storage.uploadFile(tenantId, userId, buffer, originalname, mimetype, scope);
 
       // Build response
       const fileResponse = {
@@ -76,6 +77,13 @@ export function createUploadRouter(storage, maxFileSize = 100 * 1024 * 1024) {
         });
       }
 
+      if (error.statusCode === 503) {
+        return res.status(503).json({
+          error: 'Service Unavailable',
+          message: error.message
+        });
+      }
+
       res.status(500).json({
         error: 'Internal Server Error',
         message: 'Failed to upload file'

package/HLD.md

@@ -1,170 +0,0 @@
-# @progalaxyelabs/stonescriptphp-files — High Level Design
-
-**Version**: 1.0.0
-**Last Updated**: 2026-02-07
-
-## Overview
-
-A shared npm package that provides a ready-to-use Express file server with Azure Blob Storage and JWT authentication.
-
-### Developer Experience
-```bash
-mkdir files && cd files
-npm init -y
-npm i express @progalaxyelabs/stonescriptphp-files
-```
-
-```js
-// index.js
-import 'dotenv/config';
-import { createFilesServer } from '@progalaxyelabs/stonescriptphp-files';
-createFilesServer().listen();
-```
-
-## Architecture
-
-### Package Exports
-
-```
-@progalaxyelabs/stonescriptphp-files
-├── createFilesServer(config?)    // Factory: returns configured Express app
-├── AzureStorageClient            // Class: Azure Blob Storage operations
-├── createAuthMiddleware          // Middleware factory: JWT Bearer token validation
-├── createUploadRouter            // Express Router factory: POST /upload
-├── createDownloadRouter          // Express Router factory: GET /files/:id
-├── createListRouter              // Express Router factory: GET /files
-├── createDeleteRouter            // Express Router factory: DELETE /files/:id
-└── createHealthRouter            // Express Router factory: GET /health
-```
-
-### `createFilesServer(config?)` Factory
-
-```js
-createFilesServer({
-  port: process.env.PORT || 3000,
-  containerName: process.env.AZURE_CONTAINER_NAME || 'platform-files',
-  azureConnectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
-  jwtPublicKey: process.env.JWT_PUBLIC_KEY,
-  maxFileSize: 100 * 1024 * 1024,  // 100MB default
-  corsOrigins: '*',
-});
-```
-
-All config is optional — defaults to environment variables so the minimal setup works with zero arguments.
-
-### Request Flow
-
-```
-Client
-  │
-  ├─ POST /upload (multipart/form-data)
-  │   → JWT auth middleware
-  │   → multer (memory storage)
-  │   → AzureStorageClient.uploadFile()
-  │   → Returns { success, file: { id, name, size, contentType, uploadedAt } }
-  │
-  ├─ GET /files/:id
-  │   → JWT auth middleware
-  │   → AzureStorageClient.downloadFile()
-  │   → Streams blob to response (Content-Type, Content-Disposition)
-  │
-  ├─ GET /files
-  │   → JWT auth middleware
-  │   → AzureStorageClient.listFiles(userId)
-  │   → Returns { success, count, files: [...] }
-  │
-  ├─ DELETE /files/:id
-  │   → JWT auth middleware
-  │   → AzureStorageClient.deleteFile()
-  │   → Returns { success, message }
-  │
-  └─ GET /health
-      → No auth
-      → Returns { status: "healthy", service: "files-service", timestamp }
-```
-
-## Components
-
-### createFilesServer (factory)
-Main export. Creates and returns a configured Express app with all routes, middleware, and graceful shutdown. Accepts optional config object, defaults to env vars.
-
-### AzureStorageClient (class)
-Wraps `@azure/storage-blob` SDK. Methods: `initialize()`, `uploadFile(userId, buffer, filename, contentType)`, `downloadFile(fileId, userId)`, `listFiles(userId)`, `deleteFile(fileId, userId)`. Auto-creates container on init with private access.
-
-### createAuthMiddleware (middleware factory)
-Express middleware factory. Validates Bearer token, extracts user identity from standard JWT claims (`sub`, `user_id`, `userId`, `id`), attaches to `req.user`. Supports RS256/ES256/HS256.
-
-### Route handlers (router factories)
-Express Router factory functions for upload, download, list, delete, health. Can be used individually for custom mounting or composed via `createFilesServer`.
-
-## Tech Stack
-
-| Component | Technology |
-|-----------|-----------|
-| Runtime | Node.js 24+ |
-| Framework | Express 5.x (peerDependency) |
-| Language | JavaScript (ESM) |
-| Storage | Azure Blob Storage (`@azure/storage-blob` ^12.24.0) |
-| Auth | JWT (`jsonwebtoken` ^9.0.2) |
-| Upload | `multer` ^1.4.5-lts.1 |
-| Module type | ESM (`"type": "module"`) |
-
-## Storage Design
-
-- **SDK:** `@azure/storage-blob` v12.x
-- **Auth:** Connection string (env var)
-- **Container:** auto-created on startup with private access
-- **Blob path:** `{userId}/{uuid}.{extension}`
-- **Metadata:** original_name, user_id, content_type, uploaded_at, file_id
-
-## JWT Authentication
-
-- **Algorithms:** RS256, ES256, HS256
-- **Token source:** `Authorization: Bearer <token>` header
-- **User ID extraction:** `sub` | `user_id` | `userId` | `id` claim
-- **Ownership:** files are scoped to the authenticated user's ID
-- **Health endpoint:** excluded from auth
-- **Role-based auth:** optional `requireRole()` middleware export
-
-## Environment Variables
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `AZURE_STORAGE_CONNECTION_STRING` | Yes | — | Azure Storage connection string |
-| `AZURE_CONTAINER_NAME` | No | `platform-files` | Blob container name |
-| `JWT_PUBLIC_KEY` | Yes | — | Public key for JWT verification |
-| `PORT` | No | `3000` | Server listen port |
-
-## Requirements
-
-### Functional
-- Upload files via multipart/form-data to Azure Blob Storage
-- Download files with ownership verification and proper headers
-- List all files belonging to the authenticated user
-- Delete files with ownership verification
-- JWT Bearer token authentication on all file operations
-- Health check endpoint (unauthenticated)
-- Auto-create Azure Blob container on startup
-- Graceful shutdown on SIGTERM/SIGINT
-- 100MB default file size limit (configurable)
-- CORS support (configurable origins)
-
-### Non-Functional
-- Zero-config startup (all settings from env vars)
-- No platform-specific code — fully generic and reusable
-- ESM module (`"type": "module"`)
-- Node.js 24+ engine requirement
-- Express 5.x as peer dependency
-
-### Developer Experience
-- Setup in 3 commands: `npm init`, `npm i express @progalaxyelabs/stonescriptphp-files`, create index.js
-- Consumer service has only 2 dependencies: `express` and this package
-- All config via env vars with sensible defaults
-- Composable exports for advanced/custom usage
-
-## Constraints
-
-- Must work with any JWT issuer (RS256/ES256/HS256)
-- No breaking changes to Docker environment variables
-- Published to npm as `@progalaxyelabs/stonescriptphp-files` (scoped, public)
-- Source: https://github.com/progalaxyelabs/stonescriptphp-files

package/project-info.yaml

@@ -1,119 +0,0 @@
-# project-info.yaml
-# Human-readable project metadata and configuration
-
-# REQUIRED FIELDS
-# ===============
-
-# Project code in format: XXXX-NNN
-project_code: "STON-003"
-
-# Project name (matches directory name)
-name: "stonescriptphp-files"
-
-# Project type: platform | interconnected | standalone
-type: "standalone"
-
-# Project status: production | active-dev | staging | maintenance | paused | archived | planning | unknown
-status: "production"
-
-
-# BASIC METADATA
-# ==============
-
-# Human-readable project title
-title: "@progalaxyelabs/stonescriptphp-files"
-
-# Brief project description
-description: "Zero-config Express file server with Azure Blob Storage and JWT authentication"
-
-# Project version (semantic versioning recommended)
-version: "1.0.0"
-
-# Creation date (ISO 8601 format: YYYY-MM-DD)
-created: "2026-02-07"
-
-# Last modified date (ISO 8601 format: YYYY-MM-DD)
-last_modified: "2026-02-07"
-
-
-# BUSINESS CLASSIFICATION
-# =======================
-
-# Domain category
-domain: "tools"
-
-# Project purpose: product | client-project | internal-tool | poc | experiment | library | marketing | unknown
-purpose: "library"
-
-# Business model: b2b-saas | b2c-saas | b2b-one-off | b2c-one-off | marketplace | internal | unknown
-business_model: "internal"
-
-# Ownership: progalaxy | client | partner | open-source | unknown
-ownership: "open-source"
-
-# Revenue priority: p0-critical | p1-high | p2-medium | p3-low | p4-none | unknown
-revenue_priority: "p4-none"
-
-
-# TECHNICAL DETAILS
-# =================
-
-# Primary technology stack
-tech_stack:
-  language: "JavaScript (ESM)"
-  runtime: "Node.js >= 24"
-  framework: "Express 5 (peerDependency)"
-  storage: "Azure Blob Storage"
-  auth: "JWT (RS256/ES256/HS256)"
-
-# Key dependencies
-dependencies:
-  - "@azure/storage-blob"
-  - "multer"
-  - "jsonwebtoken"
-  - "cors"
-  - "uuid"
-
-# Deployment tier: tier-0-static | tier-1-simple | tier-2-database | tier-3-services | tier-4-distributed | library | unknown
-deployment_tier: "library"
-
-
-# GIT & REPOSITORY
-# ================
-
-repository:
-  type: "git"
-  url: "git@github.com:progalaxyelabs/stonescriptphp-files.git"
-  branch: "main"
-
-# Package registry
-npm:
-  name: "@progalaxyelabs/stonescriptphp-files"
-  scope: "progalaxyelabs"
-  access: "public"
-
-
-# CONSUMERS
-# =========
-
-consumers:
-  - "progalaxyelabs-platform/files"
-  - "progalaxy-platform/files"
-  - "btechrecruiter-platform/files"
-  - "instituteapp-platform/files"
-  - "restrantapp-platform/files"
-  - "medstoreapp-platform/files"
-  - "logisticsapp-platform/files"
-  - "specialcomputers-platform/files"
-  - "aasaanwork-platform/files"
-  - "webmeteor-platform/files"
-  - "emcircuitsystems-platform/files"
-
-
-# NOTES
-# =====
-
-notes: |
-  Factory pattern: createFilesServer(config?) with env var defaults.
-  Composable exports for advanced usage.
-  HLD in HLD.md.