impulse-api 3.0.1 → 3.0.2

package/package.json

@@ -4,12 +4,15 @@
   "name": "impulse-api",
   "description": "A efficient and powerful API with Express under the hood.",
   "license": "MIT",
+  "pre-commit": [
+    "test"
+  ],
   "scripts": {
     "lint": "eslint --ignore-path .gitignore .",
     "test": "nyc --reporter=lcov --reporter=text-summary mocha",
     "test-server": "node ./test/integration/test-server.js"
   },
-  "version": "3.0.1",
+  "version": "3.0.2",
   "engines": {
     "node": ">=22"
   },
@@ -19,9 +22,9 @@
     "express": "4.21.2",
     "express-fileupload": "1.5.1",
     "http-errors": "2.0.0",
-    "jsonwebtoken": "^9.0.2",
+    "jsonwebtoken": "8.5.1",
     "lodash": "4.17.21",
-    "morgan": "^1.10.1",
+    "morgan": "1.10.0",
     "multer": "1.4.5-lts.2",
     "path-to-regexp": "0.1.12"
   },
@@ -29,6 +32,7 @@
     "eslint": "^9.23.0",
     "eslint-plugin-import": "^2.31.0",
     "nyc": "^17.1.0",
+    "pre-commit": "^1.2.2",
     "sinon": "4.4.6"
   },
   "keywords": [

package/readme.md

@@ -107,6 +107,94 @@ const { Auth } = require('impulse-api');
   TokenExpiredError: [Function: TokenExpiredError] }
 ```
 
+#### Custom JWT Validation
+
+You can override JWT validation to use custom authentication providers (like Google OAuth, Auth0, etc.) instead of the default JWT validation. This is typically configured once at the server level.
+
+##### Server-Level Custom Validation (Recommended)
+```javascript
+const config = {
+    name: 'my-api',
+    port: 3000,
+    secretKey: 'fallback-secret',
+    routeDir: './routes',
+    tokenValidator: async (token, services) => {
+        // Global token validation for all routes with tokenAuth: true
+        const userInfo = await services.googleOAuth.verifyToken(token);
+        return {
+            userId: userInfo.googleId,
+            email: userInfo.email,
+            name: userInfo.name,
+            picture: userInfo.picture
+        };
+    },
+    services: {
+        googleOAuth: {
+            verifyToken: async (token) => {
+                // Your Google OAuth validation logic
+                // This would typically make an API call to Google
+                return { 
+                    googleId: 'google-123', 
+                    email: 'user@example.com',
+                    name: 'John Doe',
+                    picture: 'https://example.com/photo.jpg'
+                };
+            }
+        }
+    }
+};
+
+const api = new Impulse(config);
+```
+
+##### Per-Route Override (Optional)
+If you need different validation for specific routes, you can override the global validator:
+
+```javascript
+exports.specialRoute = {
+    name: 'specialRoute',
+    method: 'post',
+    endpoint: '/api/special',
+    version: 'v1',
+    tokenAuth: true,
+    validateToken: async (token, services) => {
+        // Override global validation for this specific route
+        const userInfo = await services.specialAuth.verifyToken(token);
+        return {
+            userId: userInfo.specialId,
+            role: userInfo.role,
+            permissions: userInfo.permissions
+        };
+    },
+    run: (services, inputs, next) => {
+        const user = inputs.decoded; // From route-specific validation
+        next(200, { message: 'Success', user });
+    }
+};
+```
+
+##### Validation Flow
+1. **Global token validator** (`config.tokenValidator`) - primary validation
+2. **Route-specific validator** (`route.validateToken`) - optional override
+3. **Default JWT validation** - fallback when no token validator is provided
+
+##### Backward Compatibility
+Existing routes without custom validators continue to work with default JWT validation. No breaking changes to the existing API.
+
+##### Error Handling
+Custom validators should throw errors for invalid tokens. The framework will catch these and return appropriate HTTP 401 responses.
+
+```javascript
+validateToken: async (token, services) => {
+    try {
+        const userInfo = await services.oauth.verifyToken(token);
+        return userInfo;
+    } catch (error) {
+        throw new Error('Invalid authentication token');
+    }
+}
+```
+
 #### Application Auth
 For `admin` type routes, Impulse-Api also provides `applicationAuth` which secures any routes behind basic key authorization provided by `appKey` in the server configuration. The `applicationAuth` can be verified and passed in the header, parameters, query, or body as `key`.
 

package/sample-routes/custom-jwt-example.js

@@ -0,0 +1,83 @@
+// Example route using server-level custom JWT validation for Google OAuth
+// The tokenValidator is configured at server initialization
+exports.scanDocument = {
+    name: 'scanDocument',
+    description: 'Scan a document with Google OAuth authentication',
+    method: 'post',
+    endpoint: '/api/scan',
+    version: 'v1',
+    tokenAuth: true,
+    // No custom validator needed - uses server-level tokenValidator
+    inputs: {
+        documentId: {
+            required: true,
+            validate: (value) => typeof value === 'string' && value.length > 0
+        },
+        scanType: {
+            required: false,
+            validate: (value) => ['text', 'image', 'pdf'].includes(value)
+        }
+    },
+    run: (services, inputs, next) => {
+        const user = inputs.decoded; // Contains Google OAuth user data from server-level tokenValidator
+        const { documentId, scanType } = inputs;
+        
+        // Process the document scan with authenticated user
+        const result = {
+            success: true,
+            documentId,
+            scanType: scanType || 'text',
+            user: {
+                id: user.userId,
+                email: user.email,
+                name: user.name,
+                picture: user.picture
+            },
+            timestamp: new Date().toISOString()
+        };
+        
+        next(200, result);
+    }
+};
+
+// Example route using global custom validator
+exports.getUserProfile = {
+    name: 'getUserProfile',
+    description: 'Get user profile with custom authentication',
+    method: 'get',
+    endpoint: '/api/profile',
+    version: 'v1',
+    tokenAuth: true,
+    // This route will use the global tokenValidator from config
+    run: (services, inputs, next) => {
+        const user = inputs.decoded; // From global tokenValidator
+        
+        const profile = {
+            userId: user.userId,
+            email: user.email,
+            lastLogin: new Date().toISOString(),
+            preferences: user.preferences || {}
+        };
+        
+        next(200, profile);
+    }
+};
+
+// Example route with default JWT validation (backward compatibility)
+exports.legacyRoute = {
+    name: 'legacyRoute',
+    description: 'Legacy route using default JWT validation',
+    method: 'get',
+    endpoint: '/api/legacy',
+    version: 'v1',
+    tokenAuth: true,
+    // No custom validator - uses default JWT validation
+    run: (services, inputs, next) => {
+        const user = inputs.decoded; // From default JWT validation
+        
+        next(200, {
+            message: 'Legacy route works with default JWT',
+            user: user
+        });
+    }
+};

package/src/auth.js

@@ -5,6 +5,13 @@ const auth = {
     },
     verifyToken(token, secretKey) {
         return jwt.verify(token, secretKey);
+    },
+    // Helper function to create custom validators
+    createCustomValidator(validatorFn) {
+        if (typeof validatorFn !== 'function') {
+            throw new Error('Custom validator must be a function');
+        }
+        return validatorFn;
     }
 };
 

package/src/server.js

@@ -36,6 +36,7 @@ class Server {
         this.heartbeat = config.heartbeat || null;
         this.container = new Container(config.services);
         this.secretKey = config.secretKey;
+        this.tokenValidator = config.tokenValidator || null;
         this.errors = config.errors || Errors;
         process.env.NODE_ENV = this.env || 'dev';
         this.configureHttpServer();
@@ -214,7 +215,19 @@ class Server {
             }
 
             try {
-                decoded = await Auth.verifyToken(token, this.secretKey);
+                // Use global token validator if provided, otherwise fall back to default JWT validation
+                if (this.tokenValidator && typeof this.tokenValidator === 'function') {
+                    decoded = await this.tokenValidator(token, this.container);
+                } else {
+                    // Default JWT validation
+                    decoded = await Auth.verifyToken(token, this.secretKey);
+                }
+                
+                // Allow route-specific validation to override the global validator
+                if (route.validateToken && typeof route.validateToken === 'function') {
+                    decoded = await route.validateToken(token, this.container);
+                }
+                
                 if (decoded.username) {
                     username = decoded.username;
                 }

package/test/custom-jwt-validation.js

@@ -0,0 +1,298 @@
+const assert = require('assert');
+const Api = require('../src/api');
+const Auth = require('../src/auth');
+
+describe('Custom JWT Validation', () => {
+    let testServer;
+    let testRouteDir;
+
+    beforeEach(() => {
+        // Create a temporary route directory for testing
+        testRouteDir = '/tmp/test-routes';
+        require('fs').mkdirSync(testRouteDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        // Clean up test route directory
+        if (require('fs').existsSync(testRouteDir)) {
+            require('fs').rmSync(testRouteDir, { recursive: true, force: true });
+        }
+    });
+
+    describe('Server-Level Custom Validator', () => {
+        it('should use server-level custom validator when provided', async () => {
+            const customValidator = async (token, services) => {
+                if (token === 'valid-custom-token') {
+                    return { 
+                        userId: 'test-user-123', 
+                        email: 'test@example.com',
+                        customField: 'custom-value'
+                    };
+                }
+                throw new Error('Invalid token');
+            };
+
+            const config = {
+                name: 'test-api',
+                routeDir: testRouteDir,
+                secretKey: 'test-secret',
+                tokenValidator: customValidator,
+                services: {
+                    testService: { name: 'test' }
+                }
+            };
+
+            // Create a test route file
+            const testRoute = `
+exports.testRoute = {
+    name: 'testRoute',
+    method: 'get',
+    endpoint: '/test',
+    version: 'v1',
+    tokenAuth: true,
+    run: (services, inputs, next) => {
+        next(200, { 
+            message: 'Success',
+            user: inputs.decoded
+        });
+    }
+};
+`;
+            require('fs').writeFileSync(`${testRouteDir}/test.js`, testRoute);
+
+            const api = new Api(config);
+            await api.init();
+
+            // Test would require actual HTTP request, but we can test the validator function directly
+            const result = await customValidator('valid-custom-token', {});
+            assert.deepStrictEqual(result, {
+                userId: 'test-user-123',
+                email: 'test@example.com',
+                customField: 'custom-value'
+            });
+        });
+
+        it('should fall back to default JWT validation when no custom validator', async () => {
+            const config = {
+                name: 'test-api',
+                routeDir: testRouteDir,
+                secretKey: 'test-secret',
+                services: {}
+            };
+
+            // Create a test route file
+            const testRoute = `
+exports.testRoute = {
+    name: 'testRoute',
+    method: 'get',
+    endpoint: '/test',
+    version: 'v1',
+    tokenAuth: true,
+    run: (services, inputs, next) => {
+        next(200, { message: 'Success' });
+    }
+};
+`;
+            require('fs').writeFileSync(`${testRouteDir}/test.js`, testRoute);
+
+            const api = new Api(config);
+            await api.init();
+
+            // Test default JWT validation
+            const token = Auth.generateToken({ userId: 'test-user' }, { secretKey: 'test-secret' });
+            const decoded = Auth.verifyToken(token, 'test-secret');
+            assert.strictEqual(decoded.userId, 'test-user');
+        });
+    });
+
+    describe('Route-Specific Override', () => {
+        it('should allow route-specific validator to override server-level validator', async () => {
+            const serverValidator = async (token, services) => {
+                return { userId: 'server-user', source: 'server' };
+            };
+
+            const routeValidator = async (token, services) => {
+                if (token === 'route-specific-token') {
+                    return { 
+                        userId: 'route-user-456', 
+                        email: 'route@example.com',
+                        source: 'route'
+                    };
+                }
+                throw new Error('Invalid route token');
+            };
+
+            const config = {
+                name: 'test-api',
+                routeDir: testRouteDir,
+                secretKey: 'test-secret',
+                tokenValidator: serverValidator,
+                services: {}
+            };
+
+            // Create a test route file with custom validator override
+            const testRoute = `
+exports.testRoute = {
+    name: 'testRoute',
+    method: 'get',
+    endpoint: '/test',
+    version: 'v1',
+    tokenAuth: true,
+    validateToken: async (token, services) => {
+        if (token === 'route-specific-token') {
+            return { 
+                userId: 'route-user-456', 
+                email: 'route@example.com',
+                source: 'route'
+            };
+        }
+        throw new Error('Invalid route token');
+    },
+    run: (services, inputs, next) => {
+        next(200, { 
+            message: 'Success',
+            user: inputs.decoded
+        });
+    }
+};
+`;
+            require('fs').writeFileSync(`${testRouteDir}/test.js`, testRoute);
+
+            const api = new Api(config);
+            await api.init();
+
+            // Test the route-specific validator
+            const result = await routeValidator('route-specific-token', {});
+            assert.deepStrictEqual(result, {
+                userId: 'route-user-456',
+                email: 'route@example.com',
+                source: 'route'
+            });
+        });
+
+        it('should use server-level validator when no route-specific validator', async () => {
+            const serverValidator = async (token, services) => {
+                return { userId: 'server-user', source: 'server' };
+            };
+
+            const config = {
+                name: 'test-api',
+                routeDir: testRouteDir,
+                secretKey: 'test-secret',
+                tokenValidator: serverValidator,
+                services: {}
+            };
+
+            // Create a test route file without custom validator
+            const testRoute = `
+exports.testRoute = {
+    name: 'testRoute',
+    method: 'get',
+    endpoint: '/test',
+    version: 'v1',
+    tokenAuth: true,
+    run: (services, inputs, next) => {
+        next(200, { 
+            message: 'Success',
+            user: inputs.decoded
+        });
+    }
+};
+`;
+            require('fs').writeFileSync(`${testRouteDir}/test.js`, testRoute);
+
+            const api = new Api(config);
+            await api.init();
+
+            // Test that server validator is used
+            const result = await serverValidator('any-token', {});
+            assert.strictEqual(result.source, 'server');
+        });
+    });
+
+    describe('Error Handling', () => {
+        it('should handle custom validator errors gracefully', async () => {
+            const failingValidator = async (token, services) => {
+                throw new Error('Custom validation failed');
+            };
+
+            const config = {
+                name: 'test-api',
+                routeDir: testRouteDir,
+                secretKey: 'test-secret',
+                tokenValidator: failingValidator,
+                services: {}
+            };
+
+            // Create a test route file
+            const testRoute = `
+exports.testRoute = {
+    name: 'testRoute',
+    method: 'get',
+    endpoint: '/test',
+    version: 'v1',
+    tokenAuth: true,
+    run: (services, inputs, next) => {
+        next(200, { message: 'Success' });
+    }
+};
+`;
+            require('fs').writeFileSync(`${testRouteDir}/test.js`, testRoute);
+
+            const api = new Api(config);
+            await api.init();
+
+            // Test that validator throws expected error
+            try {
+                await failingValidator('invalid-token', {});
+                assert.fail('Should have thrown an error');
+            } catch (error) {
+                assert.strictEqual(error.message, 'Custom validation failed');
+            }
+        });
+
+        it('should validate custom validator function type', () => {
+            assert.throws(() => {
+                Auth.createCustomValidator('not-a-function');
+            }, /Custom validator must be a function/);
+
+            assert.doesNotThrow(() => {
+                Auth.createCustomValidator(() => {});
+            });
+        });
+    });
+
+    describe('Backward Compatibility', () => {
+        it('should work with existing routes without custom validation', async () => {
+            const config = {
+                name: 'test-api',
+                routeDir: testRouteDir,
+                secretKey: 'test-secret',
+                services: {}
+            };
+
+            // Create a test route file without custom validation
+            const testRoute = `
+exports.testRoute = {
+    name: 'testRoute',
+    method: 'get',
+    endpoint: '/test',
+    version: 'v1',
+    tokenAuth: true,
+    run: (services, inputs, next) => {
+        next(200, { message: 'Success' });
+    }
+};
+`;
+            require('fs').writeFileSync(`${testRouteDir}/test.js`, testRoute);
+
+            const api = new Api(config);
+            await api.init();
+
+            // Test that default JWT validation still works
+            const token = Auth.generateToken({ userId: 'legacy-user' }, { secretKey: 'test-secret' });
+            const decoded = Auth.verifyToken(token, 'test-secret');
+            assert.strictEqual(decoded.userId, 'legacy-user');
+        });
+    });
+});