secure-gateway-sdk 1.0.0

package/README.md

@@ -0,0 +1,70 @@
+# Security Gateway SDK - Proxy Library
+
+This package is a drop-in API Gateway library designed to secure and route traffic to a microservice ecosystem containing Auth, Enclave, and Audit endpoints. 
+
+It acts exclusively as an Express Middleware router.
+
+## How to use this Library
+
+As a third-party developer (Client), you will include this library inside your own backend express server to instantly spin up the Security Gateway shield over your logic.
+
+### 1. Installation
+Ensure you have the gateway folder available in your workspace (or published via NPM if deployed).
+
+### 2. Integration Example (Your main app)
+```javascript
+const express = require('express');
+const { SecurityGateway } = require('security-gateway-sdk/proxy');
+
+const app = express();
+
+// Mount the Security Gateway to any route string (e.g. /api)
+app.use('/api', SecurityGateway({
+    jwtSecret: 'process.env.MY_SECRET', // Required: For verifying tokens
+    authTarget: 'http://localhost:7001', // Your custom configured Auth backend
+    enclaveTarget: 'http://localhost:4000', // Your Enclave
+    auditTarget: 'http://localhost:5000' 
+}));
+
+app.listen(3000, () => {
+    console.log('Main Application running on port 3000');
+});
+```
+
+### Routing Rules Under the Hood
+Once mounted (for example at `/api`), the library automatically protects traffic:
+* `POST /api/auth/register` -> Publicly proxies to `authTarget`
+* `GET /api/enclave/data` -> Instantly intercepted! Extracts JWT, validates against `jwtSecret`, and passes to `enclaveTarget` only if valid.
+
+---
+
+## Testing (cURL Examples)
+
+Since we mounted the `SecurityGateway` directly into the Auth service, the Gateway is currently running actively on `http://localhost:7001/api`. You can use these commands to test the integration:
+
+### 1. Register a new user (Public Route)
+```bash
+curl -X POST http://localhost:7001/api/auth/register \
+-H "Content-Type: application/json" \
+-d '{"username": "test_user", "password": "password123", "role": "admin"}'
+```
+
+### 2. Login to get a JWT Token (Public Route)
+```bash
+curl -X POST http://localhost:7001/api/auth/login \
+-H "Content-Type: application/json" \
+-d '{"username": "test_user", "password": "password123"}'
+```
+
+### 3. Access the Enclave (Protected Route - Success)
+Replace `<YOUR_TOKEN>` with the token string received from the login command.
+```bash
+curl -X GET http://localhost:7001/api/enclave \
+-H "Authorization: Bearer <YOUR_TOKEN>"
+```
+
+### 4. Access the Enclave (Protected Route - Failure)
+If you try to access the enclave without attaching the token header, the SDK will proactively block you.
+```bash
+curl -X GET http://localhost:7001/api/enclave
+```

package/index.js

@@ -0,0 +1,107 @@
+const express = require('express');
+const { createProxyMiddleware } = require('http-proxy-middleware');
+const { createSecurityMiddleware } = require('./middleware/security');
+const { createMLSMiddleware } = require('./middleware/mls'); // <--- Import MLS Engine
+
+/**
+ * Universal Security Gateway Library (Publishable SDK)
+ * Dynamic configuration for securing any microservice architecture.
+ *
+ * @param {Object} options Configuration Object
+ * @param {string} options.jwtSecret The verification secret for Tokens
+ * @param {Array} options.routes Array defining paths, targets, and protection logic
+ */
+function SecurityGateway(options) {
+    const router = express.Router();
+
+    if (!options || !options.jwtSecret) {
+        throw new Error('[SecurityGateway] Fatal: "jwtSecret" must be provided in configuration options.');
+    }
+
+    const verifyToken = createSecurityMiddleware(options.jwtSecret);
+
+    if (options.routes && Array.isArray(options.routes)) {
+        options.routes.forEach(route => {
+            const proxyConfig = {
+                target: route.target,
+                changeOrigin: true
+            };
+
+            // Custom rewrite rules provided by the implementing developer
+            if (route.pathRewrite) {
+                proxyConfig.pathRewrite = route.pathRewrite;
+            }
+
+            // Chain middlewares dynamically depending on if route is protected
+            const middlewares = [];
+            if (route.protected) {
+                // Step 1: Extract and verify JWT
+                middlewares.push(verifyToken);
+                
+                // Step 2: Inject Bell-LaPadula rules if clearance is specified for the route!
+                if (route.requiredClearance) {
+                    middlewares.push(createMLSMiddleware(route.requiredClearance));
+                    // middlewares.push('S');
+                }
+            }
+            
+            // Step 3: Physically Forward the Request
+            if (route.useSecureChannel) {
+                const EnclaveClient = require('./lib/enclave-client');
+                const enclaveClient = new EnclaveClient(route.target, options.enclave?.mrenclave);
+                const BLSAuditSim = require('./lib/bls');
+                const blsAudit = new BLSAuditSim(options.bls?.privateKey);
+
+                // Express json parser for the proxy to read the body before encryption
+                middlewares.push(express.json());
+                middlewares.push(async (req, res) => {
+                    try {
+                        const payload = req.body && Object.keys(req.body).length > 0 ? req.body : { action: "read_data" };
+                        const token = req.headers['authorization']?.split(' ')[1];
+                        
+                        // Execute over ECDH secure channel
+                        const result = await enclaveClient.execute(payload, token);
+                        
+                        // Generate Audit Log
+                        const logEntry = {
+                            timestamp: new Date().toISOString(),
+                            user: req.user.username,
+                            clearance: req.user.clearance,
+                            action: 'enclave_execution',
+                            status: 'SUCCESS'
+                        };
+                        const sigData = blsAudit.signAndAggregate(logEntry);
+                        Object.assign(logEntry, sigData);
+                        
+                        // Send log asynchronously
+                        if (options.auditTarget) {
+                            fetch(options.auditTarget + '/log', {
+                                method: 'POST',
+                                headers: { 'Content-Type': 'application/json' },
+                                body: JSON.stringify(logEntry)
+                            }).catch(e => console.error('[Proxy] Failed to send audit log'));
+                        }
+
+                        res.json(result);
+                    } catch (error) {
+                        res.status(500).json({ error: error.message });
+                    }
+                });
+            } else {
+                middlewares.push(createProxyMiddleware(proxyConfig));
+            }
+
+            router.use(route.path, ...middlewares);
+            
+            console.log(`[SecurityGateway] Shield mounted: ${route.path} -> ${route.target} (Protected: ${!!route.protected}, MLS: ${route.requiredClearance || 'None'})`);
+        });
+    }
+
+    return router;
+}
+
+module.exports = {
+    SecurityGateway,
+    createSecurityMiddleware,
+    createMLSMiddleware
+};

package/lib/bls.js

@@ -0,0 +1,43 @@
+const crypto = require('crypto');
+
+/**
+ * Simulates BLS12-381 Aggregate Signatures for the Audit Logger.
+ * Real pairing-based crypto requires large WASM libraries (like @noble/bls12-381).
+ * We simulate the "aggregation" property here using chained SHA-256 hashes.
+ * 
+ * Property simulated: N events produce a single constant-size proof.
+ */
+class BLSAuditSim {
+    constructor(privateKey) {
+        // Use injected private key instead of hardcoded config
+        this.privateKey = privateKey || 'default_bls_key';
+        this.aggregateSignature = crypto.createHash('sha256').update('GENESIS').digest('hex');
+        this.sigCount = 0;
+    }
+
+    /**
+     * Signs a single log entry and aggregates it into the session proof.
+     */
+    signAndAggregate(eventPayload) {
+        // 1. Sign the individual event
+        const hmac = crypto.createHmac('sha256', this.privateKey);
+        hmac.update(JSON.stringify(eventPayload));
+        const eventSig = hmac.digest('hex');
+
+        // 2. Aggregate: Combine the new signature with the existing aggregate signature
+        // In real BLS this is scalar point addition. Here we simulate it by hashing them together.
+        const aggregator = crypto.createHash('sha256');
+        aggregator.update(this.aggregateSignature + eventSig);
+        this.aggregateSignature = aggregator.digest('hex');
+        
+        this.sigCount++;
+        
+        return {
+            eventSig,
+            aggregateSignature: this.aggregateSignature,
+            sigIndex: this.sigCount
+        };
+    }
+}
+
+module.exports = BLSAuditSim;

package/lib/crypto.js

@@ -0,0 +1,95 @@
+const crypto = require('crypto');
+
+/**
+ * SecureChannel implements the Elliptic-Curve Diffie-Hellman (ECDH) key exchange
+ * and AES-256-GCM authenticated encryption for secure communication.
+ * 
+ * This fulfills the Confidentiality and Integrity requirements of the CIA triad.
+ */
+class SecureChannel {
+    constructor() {
+        // Using secp256k1, the standard curve used in many high-security applications
+        this.ecdh = crypto.createECDH('secp256k1');
+        this.ecdh.generateKeys();
+        this.aesKey = null;
+    }
+
+    /**
+     * Gets the public key to share with the other untrusted party.
+     * @returns {string} Hexadecimal representation of the public key
+     */
+    getPublicKey() {
+        return this.ecdh.getPublicKey('hex');
+    }
+
+    /**
+     * Computes the shared symmetric secret using the other party's public key.
+     * @param {string} otherPublicKeyHex 
+     */
+    computeSharedSecret(otherPublicKeyHex) {
+        // ECDH math: Your Private Key + Their Public Key = Shared Secret
+        const sharedSecret = this.ecdh.computeSecret(otherPublicKeyHex, 'hex');
+        
+        // We hash the shared secret with SHA-256 to ensure we get a perfect 32-byte key for AES-256
+        this.aesKey = crypto.createHash('sha256').update(sharedSecret).digest();
+        return true;
+    }
+
+    /**
+     * Encrypts a payload using AES-256-GCM.
+     * @param {Object|string} payload The data to encrypt
+     * @returns {Object} The encryption envelope containing ciphertext, iv, and auth tag
+     */
+    encrypt(payload) {
+        if (!this.aesKey) throw new Error("Security Error: Shared secret not computed yet.");
+        
+        // GCM standard requires a unique 12-byte (96-bit) Initialization Vector per encryption
+        const iv = crypto.randomBytes(12); 
+        
+        const cipher = crypto.createCipheriv('aes-256-gcm', this.aesKey, iv);
+        
+        const stringifiedPayload = typeof payload === 'string' ? payload : JSON.stringify(payload);
+        let ciphertext = cipher.update(stringifiedPayload, 'utf8', 'hex');
+        ciphertext += cipher.final('hex');
+        
+        // The Authentication Tag provides Integrity - it proves the ciphertext hasn't been tampered with
+        const authTag = cipher.getAuthTag().toString('hex');
+
+        return {
+            ciphertext,
+            iv: iv.toString('hex'),
+            authTag
+        };
+    }
+
+    /**
+     * Decrypts an AES-256-GCM encrypted envelope.
+     * @param {Object} envelope The envelope containing ciphertext, iv, and authTag
+     * @returns {Object|string} The decrypted plaintext
+     */
+    decrypt({ ciphertext, iv, authTag }) {
+        if (!this.aesKey) throw new Error("Security Error: Shared secret not computed yet.");
+
+        const decipher = crypto.createDecipheriv(
+            'aes-256-gcm', 
+            this.aesKey, 
+            Buffer.from(iv, 'hex')
+        );
+        
+        // Set the auth tag to verify integrity before decryption
+        decipher.setAuthTag(Buffer.from(authTag, 'hex'));
+
+        let decrypted = decipher.update(ciphertext, 'hex', 'utf8');
+        decrypted += decipher.final('utf8'); // Will throw error if tampered!
+
+        try {
+            return JSON.parse(decrypted);
+        } catch (e) {
+            return decrypted; // Fallback if plaintext was just a string
+        }
+    }
+}
+
+module.exports = {
+    SecureChannel
+};

package/lib/enclave-client.js

@@ -0,0 +1,79 @@
+const { SecureChannel } = require('./crypto');
+const crypto = require('crypto');
+
+/**
+ * EnclaveClient acts as the secure intermediary between the Proxy and the TEE.
+ * It enforces Enclave Attestation and establishes an ECDH secure channel.
+ */
+class EnclaveClient {
+    constructor(enclaveUrl, expectedMrenclave) {
+        this.enclaveUrl = enclaveUrl;
+        this.expectedMrenclave = expectedMrenclave;
+        this.channel = new SecureChannel();
+        this.isAttested = false;
+    }
+
+    async attestAndHandshake() {
+        const nonce = crypto.randomBytes(16).toString('hex');
+        const clientPubKey = this.channel.getPublicKey();
+
+        // 1. Send our public key and a nonce to the Enclave
+        const response = await fetch(`${this.enclaveUrl}/attest`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ nonce, clientPublicKey: clientPubKey })
+        });
+        
+        const data = await response.json();
+
+        // 2. Verify mrenclave (Simulated hardware hash)
+        if (data.mrenclave !== this.expectedMrenclave) {
+            throw new Error('ATTESTATION FAILED: Unknown mrenclave hash! Server might be spoofed.');
+        }
+
+        // 3. Verify Quote (Simulated hardware ECDSA signature using HMAC)
+        const hmac = crypto.createHmac('sha256', 'simulated_hardware_key');
+        hmac.update(data.mrenclave + nonce + data.publicKey);
+        const expectedQuote = hmac.digest('hex');
+        
+        if (data.quote !== expectedQuote) {
+            throw new Error('ATTESTATION FAILED: Invalid hardware quote! Key exchange compromised.');
+        }
+
+        // 4. Compute shared secret with the verified enclave public key
+        this.channel.computeSharedSecret(data.publicKey);
+        this.isAttested = true;
+        console.log('[Proxy->Enclave] Attestation successful. ECDH secure channel established.');
+    }
+
+    async execute(payload, token) {
+        // If we haven't verified the enclave yet, do it now
+        if (!this.isAttested) {
+            await this.attestAndHandshake();
+        }
+
+        // Encrypt the payload using AES-256-GCM
+        const encrypted = this.channel.encrypt(payload);
+        
+        // Send to Enclave
+        const response = await fetch(`${this.enclaveUrl}/execute`, {
+            method: 'POST',
+            headers: { 
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${token}` // Pass the user's JWT to prove they passed proxy auth
+            },
+            body: JSON.stringify(encrypted)
+        });
+
+        const data = await response.json();
+        
+        if (!response.ok) {
+            throw new Error(data.error || 'Execution failed');
+        }
+
+        // Decrypt the response
+        return this.channel.decrypt(data);
+    }
+}
+
+module.exports = EnclaveClient;

package/middleware/mls.js

@@ -0,0 +1,69 @@
+/**
+ * MLS Engine (Multi-Level Security)
+ * Implements Bell-LaPadula Lattice logic for the SDK.
+ */
+
+const LATTICE = {
+    'U': 10, // Unclassified
+    'C': 20, // Confidential
+    'S': 30, // Secret
+    'TS': 40 // Top Secret
+};
+
+function createMLSMiddleware(routeRequiredClearance) {
+    const routeLevel = LATTICE[routeRequiredClearance?.toUpperCase()];
+
+    if (!routeLevel) {
+        throw new Error(`[MLS Engine] Fatal: Invalid clearance level provided: ${routeRequiredClearance}. Must be U, C, S, or TS.`);
+    }
+
+    return (req, res, next) => {
+        // verifyToken MUST run before this middleware so req.user exists
+        if (!req.user || !req.user.clearance) {
+            console.error('[MLS Engine] Missing clearance from JWT Payload!');
+            return res.status(403).json({ error: 'MLS Blocked: User clearance level is not defined.' });
+        }
+
+        const userLevel = LATTICE[req.user.clearance.toUpperCase()];
+        if (!userLevel) {
+            return res.status(403).json({ error: `MLS Blocked: Unknown user clearance header '${req.user.clearance}'` });
+        }
+
+        const isRead = ['GET', 'HEAD', 'OPTIONS'].includes(req.method);
+        const isWrite = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method);
+
+        // ----------------------------------------------------
+        // Rule 1: Simple Security Property (No-Read-Up)
+        // ----------------------------------------------------
+        // Users cannot read data at a classification level higher than their own.
+        if (isRead) {
+            if (userLevel < routeLevel) {
+                console.warn(`[MLS] BLocked READ-UP Attack: User(${req.user.clearance}) trying to read Route(${routeRequiredClearance})`);
+                return res.status(403).json({ 
+                    error: `Bell-LaPadula Violation: Operation denied. Your clearance (${req.user.clearance}) is too low to read this resource (${routeRequiredClearance}).` 
+                });
+            }
+        }
+
+        // ----------------------------------------------------
+        // Rule 2: *-Property (No-Write-Down)
+        // ----------------------------------------------------
+        // Users at a high classification cannot accidentally or maliciously write high-level data to a low-level target.
+        if (isWrite) {
+            if (userLevel > routeLevel) {
+                console.warn(`[MLS] Blocked WRITE-DOWN Attack: User(${req.user.clearance}) trying to write to Route(${routeRequiredClearance})`);
+                return res.status(403).json({ 
+                    error: `Bell-LaPadula Violation: Data spillage risk denied. You cannot write sensitive data (${req.user.clearance}) to a lower clearance partition (${routeRequiredClearance}).` 
+                });
+            }
+        }
+
+        // Passed lattice checks!
+        console.log(`[MLS Engine] Passed Bell-LaPadula checks for user ${req.user.sub}`);
+        next();
+    };
+}
+
+module.exports = {
+    createMLSMiddleware
+};

package/middleware/security.js

@@ -0,0 +1,44 @@
+const jwt = require('jsonwebtoken');
+
+/**
+ * Creates the security verification middleware using an injected secret.
+ * @param {string} secret The secret key used to verify the JWT signature.
+ */
+const createSecurityMiddleware = (secret) => {
+    if (!secret) {
+        throw new Error('[SecurityGateway] A JWT secret is required to initialize security middleware.');
+    }
+
+    return (req, res, next) => {
+        const authHeader = req.headers['authorization'];
+        
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            console.warn('[SecurityGateway] Blocked request: Missing or invalid Authorization header');
+            return res.status(401).json({ error: 'Unauthorized: Missing token' });
+        }
+
+        const token = authHeader.split(' ')[1];
+
+        try {
+            const decoded = jwt.verify(token, secret);
+            
+            // Attach the fully decoded token metadata to the request
+            req.user = decoded;
+            
+            // Inject into headers so downstream client microservices know who the user is
+            req.headers['x-user-id'] = decoded.sub;
+            req.headers['x-user-role'] = decoded.role;
+            req.headers['x-user-clearance'] = decoded.clearance;
+            
+            console.log(`[SecurityGateway] Authorized request for user ${decoded.username} (${decoded.role})`);
+            next();
+        } catch (error) {
+            console.warn(`[SecurityGateway] Blocked request: Invalid token - ${error.message}`);
+            return res.status(403).json({ error: 'Forbidden: Invalid or expired token' });
+        }
+    };
+};
+
+module.exports = {
+    createSecurityMiddleware
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "secure-gateway-sdk",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "echo 'Proxy is an SDK library and cannot be run directly. Import it into your own server script.' && exit 0"
+  },
+  "dependencies": {
+    "cors": "^2.8.6",
+    "dotenv": "^16.6.1",
+    "express": "^5.2.1",
+    "http-proxy-middleware": "^3.0.5",
+    "jsonwebtoken": "^9.0.3"
+  },
+  "description": "This package is a drop-in API Gateway library designed to secure and route traffic to a microservice ecosystem containing Auth, Enclave, and Audit endpoints.",
+  "main": "index.js",
+  "directories": {
+    "lib": "lib"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs"
+}