@progalaxyelabs/stonescriptphp-files 1.0.0 → 2.0.0

package/HLD.md

@@ -0,0 +1,170 @@
+# @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/README.md

@@ -1,6 +1,6 @@
 # @progalaxyelabs/stonescriptphp-files
 
-Shared file server for ProGalaxy E-Labs platforms — Azure Blob Storage + JWT auth
+Zero-config Express file server with Azure Blob Storage and JWT authentication
 
 ## Installation
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@progalaxyelabs/stonescriptphp-files",
-  "version": "1.0.0",
-  "description": "Shared file server for ProGalaxy E-Labs platforms — Azure Blob Storage + JWT auth",
+  "version": "2.0.0",
+  "description": "Zero-config Express file server with Azure Blob Storage and JWT authentication",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -18,7 +18,8 @@
     "multer": "^1.4.5-lts.1",
     "jsonwebtoken": "^9.0.2",
     "cors": "^2.8.5",
-    "uuid": "^11.0.5"
+    "uuid": "^11.0.5",
+    "express-rate-limit": "^7.4.0"
   },
   "keywords": [
     "azure",

package/project-info.yaml

@@ -0,0 +1,119 @@
+# 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.

package/src/auth.js

@@ -41,9 +41,13 @@ export function createAuthMiddleware(publicKey) {
         });
       }
 
+      // Extract tenant_id from token
+      const tenantId = decoded.tenant_id || decoded.tid || decoded.tenant_uuid || null;
+
       // Attach user info to request
       req.user = {
         id: userId,
+        tenantId,
         email: decoded.email,
         roles: decoded.roles || [],
         ...decoded
@@ -75,6 +79,85 @@ export function createAuthMiddleware(publicKey) {
   };
 }
 
+/**
+ * JWKS-based JWT validation middleware factory
+ * Creates a middleware that validates JWT tokens using JWKS (JSON Web Key Sets)
+ *
+ * @param {JwksClient} jwksClient - JWKS client instance for key retrieval
+ * @returns {Function} Express middleware function
+ */
+export function createJwksAuthMiddleware(jwksClient) {
+  if (!jwksClient) {
+    throw new Error('JWKS client is required');
+  }
+
+  return async function authenticateJwks(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 {
+      // Get signing key from JWKS
+      const { key, algorithm } = await jwksClient.getSigningKey(token);
+
+      // Verify token with the retrieved key
+      const decoded = jwt.verify(token, key, { algorithms: [algorithm] });
+
+      // Extract user_id from token
+      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'
+        });
+      }
+
+      // Extract tenant_id from token
+      const tenantId = decoded.tenant_id || decoded.tid || decoded.tenant_uuid || null;
+
+      // Attach user info to request
+      req.user = {
+        id: userId,
+        tenantId,
+        email: decoded.email,
+        roles: decoded.roles || [],
+        ...decoded
+      };
+
+      next();
+    } catch (error) {
+      console.error('JWKS 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

package/src/azure-storage.js

@@ -42,21 +42,23 @@ export class AzureStorageClient {
 
   /**
    * Upload file to Azure Blob Storage
+   * @param {string} tenantId - Tenant ID (for multi-tenant namespacing)
    * @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) {
+  async uploadFile(tenantId, userId, fileBuffer, originalFilename, contentType) {
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
-    // Generate unique blob name: {user_id}/{uuid}.{ext}
+    // Generate unique blob name with tenant prefix: {tenant_id}/{user_id}/{uuid}.{ext}
     const fileId = uuidv4();
     const extension = originalFilename.split('.').pop();
-    const blobName = `${userId}/${fileId}.${extension}`;
+    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
+    const blobName = `${prefix}${fileId}.${extension}`;
 
     const blockBlobClient = this.containerClient.getBlockBlobClient(blobName);
 
@@ -66,6 +68,7 @@ export class AzureStorageClient {
         blobContentType: contentType
       },
       metadata: {
+        tenant_id: tenantId || '',
         user_id: userId,
         original_filename: originalFilename,
         content_type: contentType,
@@ -77,6 +80,7 @@ export class AzureStorageClient {
     return {
       fileId,
       blobName,
+      tenantId,
       userId,
       originalFilename,
       contentType,
@@ -88,17 +92,19 @@ export class AzureStorageClient {
   /**
    * Download file from Azure Blob Storage
    * @param {string} fileId - File ID (UUID)
+   * @param {string} tenantId - Tenant ID (for multi-tenant namespacing)
    * @param {string} userId - User ID (for authorization)
    * @returns {Object} { stream, metadata }
    */
-  async downloadFile(fileId, userId) {
+  async downloadFile(fileId, tenantId, userId) {
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
-    // List blobs with file_id metadata to find the blob
+    // List blobs with prefix to find the blob
+    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
     const blobs = this.containerClient.listBlobsFlat({
-      prefix: `${userId}/`,
+      prefix,
       includeMetadata: true
     });
 
@@ -130,17 +136,19 @@ export class AzureStorageClient {
 
   /**
    * List user's files
+   * @param {string} tenantId - Tenant ID (for multi-tenant namespacing)
    * @param {string} userId - User ID
    * @returns {Array} List of file metadata
    */
-  async listFiles(userId) {
+  async listFiles(tenantId, userId) {
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
     const files = [];
+    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
     const blobs = this.containerClient.listBlobsFlat({
-      prefix: `${userId}/`,
+      prefix,
       includeMetadata: true
     });
 
@@ -162,16 +170,18 @@ export class AzureStorageClient {
   /**
    * Delete file from Azure Blob Storage
    * @param {string} fileId - File ID (UUID)
+   * @param {string} tenantId - Tenant ID (for multi-tenant namespacing)
    * @param {string} userId - User ID (for authorization)
    */
-  async deleteFile(fileId, userId) {
+  async deleteFile(fileId, tenantId, userId) {
     if (!this.containerClient) {
       throw new Error('Azure Storage not initialized');
     }
 
     // Find blob by file_id
+    const prefix = tenantId ? `${tenantId}/${userId}/` : `${userId}/`;
     const blobs = this.containerClient.listBlobsFlat({
-      prefix: `${userId}/`,
+      prefix,
       includeMetadata: true
     });
 

package/src/index.js

@@ -1,13 +1,45 @@
 import express from 'express';
 import cors from 'cors';
 import { AzureStorageClient } from './azure-storage.js';
-import { createAuthMiddleware } from './auth.js';
+import { createAuthMiddleware, createJwksAuthMiddleware } from './auth.js';
+import { JwksClient } from './jwks-client.js';
+import { createRateLimiters } from './rate-limit.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';
 
+/**
+ * Resolve the authentication middleware based on configuration priority.
+ * Priority: authServers > jwksUrl > jwtPublicKey
+ *
+ * @param {Object} config - Configuration options
+ * @returns {Function} Express middleware function for authentication
+ */
+function resolveAuthMiddleware(config) {
+  const authServersJson = config.authServers || (process.env.AUTH_SERVERS ? JSON.parse(process.env.AUTH_SERVERS) : null);
+  const jwksUrl = config.jwksUrl || process.env.JWKS_URL;
+  const jwtPublicKey = config.jwtPublicKey || process.env.JWT_PUBLIC_KEY;
+  const cacheTtl = config.jwksCacheTtl || parseInt(process.env.JWKS_CACHE_TTL) || 3600;
+
+  if (authServersJson) {
+    const jwksClient = new JwksClient(authServersJson.map(s => ({ ...s, cacheTtl })));
+    return createJwksAuthMiddleware(jwksClient);
+  }
+
+  if (jwksUrl) {
+    const jwksClient = new JwksClient([{ issuer: '*', jwksUrl, cacheTtl }]);
+    return createJwksAuthMiddleware(jwksClient);
+  }
+
+  if (jwtPublicKey) {
+    return createAuthMiddleware(jwtPublicKey);
+  }
+
+  throw new Error('No authentication method configured. Set AUTH_SERVERS, JWKS_URL, or JWT_PUBLIC_KEY.');
+}
+
 /**
  * Create a configured files server
  * @param {Object} config - Configuration options
@@ -15,23 +47,33 @@ import { createHealthRouter } from './routes/health.js';
  * @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 {Array} config.authServers - Array of auth server configs [{issuer, jwksUrl, cacheTtl?}]
+ * @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 {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)
+ * @param {number} config.rateLimitUpload - Max uploads per window (default: 10)
+ * @param {number} config.rateLimitDownload - Max downloads per window (default: 60)
  * @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 || '*';
+  const tenantScoped = config.tenantScoped !== undefined ? config.tenantScoped : (process.env.TENANT_SCOPED !== 'false');
 
   // Create storage client
   const storage = new AzureStorageClient(connectionString, containerName);
 
-  // Create auth middleware
-  const authenticate = createAuthMiddleware(jwtPublicKey);
+  // Resolve auth middleware based on config priority
+  const authenticate = resolveAuthMiddleware(config);
+
+  // Create rate limiters
+  const { uploadLimiter, downloadLimiter } = createRateLimiters(config);
 
   // Create Express app
   const app = express();
@@ -49,12 +91,12 @@ export function createFilesServer(config = {}) {
     next();
   });
 
-  // Routes
+  // Routes with rate limiters
   app.use(createHealthRouter());
-  app.use(authenticate, createUploadRouter(storage, maxFileSize));
-  app.use(authenticate, createDownloadRouter(storage));
-  app.use(authenticate, createListRouter(storage));
-  app.use(authenticate, createDeleteRouter(storage));
+  app.use(authenticate, uploadLimiter, createUploadRouter(storage, maxFileSize));
+  app.use(authenticate, downloadLimiter, createDownloadRouter(storage));
+  app.use(authenticate, downloadLimiter, createListRouter(storage));
+  app.use(authenticate, downloadLimiter, createDeleteRouter(storage));
 
   // 404 handler
   app.use((req, res) => {
@@ -106,7 +148,9 @@ export function createFilesServer(config = {}) {
 
 // Named exports for advanced/composable usage
 export { AzureStorageClient } from './azure-storage.js';
-export { createAuthMiddleware } from './auth.js';
+export { createAuthMiddleware, createJwksAuthMiddleware } from './auth.js';
+export { JwksClient } from './jwks-client.js';
+export { createRateLimiters } from './rate-limit.js';
 export { createUploadRouter } from './routes/upload.js';
 export { createDownloadRouter } from './routes/download.js';
 export { createListRouter } from './routes/list.js';

package/src/jwks-client.js

@@ -0,0 +1,59 @@
+import crypto from 'crypto';
+import jwt from 'jsonwebtoken';
+
+export class JwksClient {
+  constructor(authServers) {
+    // authServers: [{issuer, jwksUrl, cacheTtl?}]
+    this.authServers = authServers;
+    this.cache = new Map(); // key: issuerKey, value: {jwks, fetchedAt}
+    this.defaultCacheTtl = 3600 * 1000; // 1 hour in ms
+  }
+
+  async getSigningKey(token) {
+    // 1. Decode token header (without verification) to get kid and iss
+    const decoded = jwt.decode(token, { complete: true });
+    if (!decoded) throw new Error('Invalid token');
+
+    const { kid, alg } = decoded.header;
+    const iss = decoded.payload.iss;
+
+    // 2. Find matching auth server by issuer (or use first if iss is '*' or not found)
+    const server = this.authServers.find(s => s.issuer === iss || s.issuer === '*') || this.authServers[0];
+    if (!server) throw new Error('No auth server configured for issuer: ' + iss);
+
+    // 3. Fetch JWKS (cached)
+    const jwks = await this.fetchJwks(server.issuer, server);
+
+    // 4. Find key by kid
+    const jwk = jwks.keys.find(k => k.kid === kid);
+    if (!jwk) throw new Error('Signing key not found for kid: ' + kid);
+
+    // 5. Convert JWK to PEM
+    const key = this.jwkToPem(jwk);
+
+    return { key, algorithm: alg || 'RS256' };
+  }
+
+  async fetchJwks(issuerKey, serverConfig) {
+    const cacheTtl = (serverConfig.cacheTtl || this.defaultCacheTtl / 1000) * 1000;
+    const cached = this.cache.get(issuerKey);
+
+    if (cached && (Date.now() - cached.fetchedAt) < cacheTtl) {
+      return cached.jwks;
+    }
+
+    const response = await fetch(serverConfig.jwksUrl);
+    if (!response.ok) {
+      throw new Error('Failed to fetch JWKS from ' + serverConfig.jwksUrl + ': ' + response.status);
+    }
+
+    const jwks = await response.json();
+    this.cache.set(issuerKey, { jwks, fetchedAt: Date.now() });
+
+    return jwks;
+  }
+
+  jwkToPem(jwk) {
+    return crypto.createPublicKey({ key: jwk, format: 'jwk' });
+  }
+}

package/src/rate-limit.js

@@ -0,0 +1,29 @@
+import rateLimit from 'express-rate-limit';
+
+export function createRateLimiters(config = {}) {
+  const windowMs = config.rateLimitWindowMs || parseInt(process.env.RATE_LIMIT_WINDOW_MS) || 60 * 1000;
+  const uploadMax = config.rateLimitUpload || parseInt(process.env.RATE_LIMIT_UPLOAD) || 10;
+  const downloadMax = config.rateLimitDownload || parseInt(process.env.RATE_LIMIT_DOWNLOAD) || 60;
+
+  const keyGenerator = (req) => req.user?.id || req.ip;
+
+  const uploadLimiter = rateLimit({
+    windowMs,
+    max: uploadMax,
+    keyGenerator,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Too Many Requests', message: 'Upload rate limit exceeded. Try again later.' }
+  });
+
+  const downloadLimiter = rateLimit({
+    windowMs,
+    max: downloadMax,
+    keyGenerator,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Too Many Requests', message: 'Rate limit exceeded. Try again later.' }
+  });
+
+  return { uploadLimiter, downloadLimiter };
+}

package/src/routes/delete.js

@@ -18,6 +18,7 @@ export function createDeleteRouter(storage) {
     try {
       const fileId = req.params.id;
       const userId = req.user.id;
+      const tenantId = req.user.tenantId;
 
       // 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,7 +30,7 @@ export function createDeleteRouter(storage) {
       }
 
       // Delete file from Azure (validates ownership)
-      await storage.deleteFile(fileId, userId);
+      await storage.deleteFile(fileId, tenantId, userId);
 
       res.status(200).json({
         success: true,

package/src/routes/download.js

@@ -18,6 +18,7 @@ export function createDownloadRouter(storage) {
     try {
       const fileId = req.params.id;
       const userId = req.user.id;
+      const tenantId = req.user.tenantId;
 
       // 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,7 +30,7 @@ export function createDownloadRouter(storage) {
       }
 
       // Download file from Azure (validates ownership)
-      const { stream, metadata } = await storage.downloadFile(fileId, userId);
+      const { stream, metadata } = await storage.downloadFile(fileId, tenantId, userId);
 
       // Set response headers
       res.setHeader('Content-Type', metadata.contentType);

package/src/routes/list.js

@@ -17,9 +17,10 @@ export function createListRouter(storage) {
   router.get('/files', async (req, res) => {
     try {
       const userId = req.user.id;
+      const tenantId = req.user.tenantId;
 
       // List files for current user
-      const files = await storage.listFiles(userId);
+      const files = await storage.listFiles(tenantId, userId);
 
       res.status(200).json({
         success: true,

package/src/routes/upload.js

@@ -41,21 +41,30 @@ export function createUploadRouter(storage, maxFileSize = 100 * 1024 * 1024) {
       }
 
       const userId = req.user.id;
+      const tenantId = req.user.tenantId;
       const { buffer, originalname, mimetype } = req.file;
 
       // Upload to Azure Blob Storage
-      const fileMetadata = await storage.uploadFile(userId, buffer, originalname, mimetype);
+      const fileMetadata = await storage.uploadFile(tenantId, userId, buffer, originalname, mimetype);
+
+      // Build response
+      const fileResponse = {
+        id: fileMetadata.fileId,
+        name: fileMetadata.originalFilename,
+        contentType: fileMetadata.contentType,
+        size: fileMetadata.size,
+        uploadedAt: fileMetadata.uploadedAt
+      };
+
+      // Include tenantId in response if present
+      if (tenantId) {
+        fileResponse.tenantId = tenantId;
+      }
 
       // 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
-        }
+        file: fileResponse
       });
     } catch (error) {
       console.error('Upload error:', error);