@friggframework/core 2.0.0--canary.461.65a2be7.0 → 2.0.0--canary.461.0b53aff.0

package/user/tests/use-cases/get-user-from-x-frigg-headers.test.js

@@ -0,0 +1,345 @@
+const Boom = require('@hapi/boom');
+const { GetUserFromXFriggHeaders } = require('../../use-cases/get-user-from-x-frigg-headers');
+const { User } = require('../../user');
+
+describe('GetUserFromXFriggHeaders', () => {
+    let getUserFromXFriggHeaders;
+    let mockUserRepository;
+    let mockUserConfig;
+
+    beforeEach(() => {
+        mockUserRepository = {
+            findIndividualUserByAppUserId: jest.fn(),
+            findOrganizationUserByAppOrgId: jest.fn(),
+            createIndividualUser: jest.fn(),
+            createOrganizationUser: jest.fn(),
+        };
+
+        mockUserConfig = {
+            usePassword: false,
+            primary: 'individual',
+            individualUserRequired: true,
+            organizationUserRequired: false,
+        };
+
+        getUserFromXFriggHeaders = new GetUserFromXFriggHeaders({
+            userRepository: mockUserRepository,
+            userConfig: mockUserConfig,
+        });
+    });
+
+    describe('Validation', () => {
+        it('should throw 400 error when neither appUserId nor appOrgId provided', async () => {
+            await expect(
+                getUserFromXFriggHeaders.execute(null, null)
+            ).rejects.toThrow(Boom.badRequest().message);
+
+            await expect(
+                getUserFromXFriggHeaders.execute(undefined, undefined)
+            ).rejects.toThrow();
+        });
+    });
+
+    describe('Find Existing User', () => {
+        it('should find existing individual user by appUserId', async () => {
+            const mockIndividualUser = {
+                id: 'user-123',
+                appUserId: 'app-user-456',
+                username: 'testuser',
+            };
+
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                mockIndividualUser
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                'app-user-456',
+                null
+            );
+
+            expect(result).toBeInstanceOf(User);
+            expect(
+                mockUserRepository.findIndividualUserByAppUserId
+            ).toHaveBeenCalledWith('app-user-456');
+            expect(
+                mockUserRepository.createIndividualUser
+            ).not.toHaveBeenCalled();
+        });
+
+        it('should find existing organization user by appOrgId', async () => {
+            mockUserConfig.organizationUserRequired = true;
+            mockUserConfig.primary = 'organization';
+
+            const mockOrgUser = {
+                id: 'org-123',
+                appOrgId: 'app-org-456',
+            };
+
+            mockUserRepository.findOrganizationUserByAppOrgId.mockResolvedValue(
+                mockOrgUser
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                null,
+                'app-org-456'
+            );
+
+            expect(result).toBeInstanceOf(User);
+            expect(
+                mockUserRepository.findOrganizationUserByAppOrgId
+            ).toHaveBeenCalledWith('app-org-456');
+            expect(
+                mockUserRepository.createOrganizationUser
+            ).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('Auto-create User', () => {
+        it('should create new individual user when appUserId not found', async () => {
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                null
+            );
+
+            const mockCreatedUser = {
+                id: 'user-new',
+                appUserId: 'new-app-user',
+                username: 'app-user-new-app-user',
+                email: 'new-app-user@app.local',
+            };
+
+            mockUserRepository.createIndividualUser.mockResolvedValue(
+                mockCreatedUser
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                'new-app-user',
+                null
+            );
+
+            expect(result).toBeInstanceOf(User);
+            expect(
+                mockUserRepository.createIndividualUser
+            ).toHaveBeenCalledWith({
+                appUserId: 'new-app-user',
+                username: 'app-user-new-app-user',
+                email: 'new-app-user@app.local',
+            });
+        });
+
+        it('should create new organization user when appOrgId not found', async () => {
+            mockUserConfig.organizationUserRequired = true;
+            mockUserConfig.primary = 'organization';
+            mockUserConfig.individualUserRequired = false;
+
+            mockUserRepository.findOrganizationUserByAppOrgId.mockResolvedValue(
+                null
+            );
+
+            const mockCreatedOrgUser = {
+                id: 'org-new',
+                appOrgId: 'new-app-org',
+            };
+
+            mockUserRepository.createOrganizationUser.mockResolvedValue(
+                mockCreatedOrgUser
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                null,
+                'new-app-org'
+            );
+
+            expect(result).toBeInstanceOf(User);
+            expect(
+                mockUserRepository.createOrganizationUser
+            ).toHaveBeenCalledWith({
+                appOrgId: 'new-app-org',
+            });
+        });
+    });
+
+    describe('User ID Conflict Detection', () => {
+        it('should throw 400 error when both IDs provided but belong to different users', async () => {
+            const mockIndividualUser = {
+                id: 'user-123',
+                appUserId: 'app-user-456',
+                organizationUser: 'org-999', // Different org
+            };
+
+            const mockOrgUser = {
+                id: 'org-888', // Different ID
+                appOrgId: 'app-org-789',
+            };
+
+            mockUserConfig.organizationUserRequired = true;
+
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                mockIndividualUser
+            );
+            mockUserRepository.findOrganizationUserByAppOrgId.mockResolvedValue(
+                mockOrgUser
+            );
+
+            await expect(
+                getUserFromXFriggHeaders.execute('app-user-456', 'app-org-789')
+            ).rejects.toThrow(Boom.badRequest().message);
+
+            await expect(
+                getUserFromXFriggHeaders.execute('app-user-456', 'app-org-789')
+            ).rejects.toThrow('User ID mismatch');
+        });
+
+        it('should succeed when both IDs provided and belong to same user', async () => {
+            const mockOrgUser = {
+                id: 'org-123',
+                appOrgId: 'app-org-789',
+            };
+
+            const mockIndividualUser = {
+                id: 'user-456',
+                appUserId: 'app-user-456',
+                organizationUser: 'org-123', // Matches org user
+            };
+
+            mockUserConfig.organizationUserRequired = true;
+
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                mockIndividualUser
+            );
+            mockUserRepository.findOrganizationUserByAppOrgId.mockResolvedValue(
+                mockOrgUser
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                'app-user-456',
+                'app-org-789'
+            );
+
+            expect(result).toBeInstanceOf(User);
+            expect(
+                mockUserRepository.createIndividualUser
+            ).not.toHaveBeenCalled();
+            expect(
+                mockUserRepository.createOrganizationUser
+            ).not.toHaveBeenCalled();
+        });
+
+        it('should not validate conflict when only one ID provided', async () => {
+            const mockIndividualUser = {
+                id: 'user-123',
+                appUserId: 'app-user-456',
+            };
+
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                mockIndividualUser
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                'app-user-456',
+                null
+            );
+
+            expect(result).toBeInstanceOf(User);
+            expect(
+                mockUserRepository.findOrganizationUserByAppOrgId
+            ).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('User Config Respect', () => {
+        it('should respect individualUserRequired setting', async () => {
+            mockUserConfig.individualUserRequired = false;
+
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                null
+            );
+
+            await getUserFromXFriggHeaders.execute('app-user-test', null);
+
+            // Should not attempt to query or create individual user if not required
+            expect(
+                mockUserRepository.findIndividualUserByAppUserId
+            ).not.toHaveBeenCalled();
+        });
+
+        it('should respect organizationUserRequired setting', async () => {
+            mockUserConfig.organizationUserRequired = false;
+
+            mockUserRepository.findOrganizationUserByAppOrgId.mockResolvedValue(
+                null
+            );
+
+            const mockIndividualUser = {
+                id: 'user-123',
+                appUserId: 'app-user-456',
+            };
+
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                mockIndividualUser
+            );
+
+            await getUserFromXFriggHeaders.execute('app-user-456', 'app-org-789');
+
+            // Should not query org user if not required
+            expect(
+                mockUserRepository.findOrganizationUserByAppOrgId
+            ).not.toHaveBeenCalled();
+        });
+
+        it('should respect primary user setting', async () => {
+            mockUserConfig.primary = 'organization';
+            mockUserConfig.organizationUserRequired = true;
+
+            const mockOrgUser = {
+                id: 'org-123',
+                appOrgId: 'app-org-789',
+            };
+
+            mockUserRepository.findOrganizationUserByAppOrgId.mockResolvedValue(
+                mockOrgUser
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                null,
+                'app-org-789'
+            );
+
+            expect(result).toBeInstanceOf(User);
+            // Verify User is constructed with org as primary
+            expect(result.config.primary).toBe('organization');
+        });
+    });
+
+    describe('Edge Cases', () => {
+        it('should handle both IDs when only one user exists', async () => {
+            const mockIndividualUser = {
+                id: 'user-123',
+                appUserId: 'app-user-456',
+            };
+
+            mockUserConfig.organizationUserRequired = true;
+
+            mockUserRepository.findIndividualUserByAppUserId.mockResolvedValue(
+                mockIndividualUser
+            );
+            mockUserRepository.findOrganizationUserByAppOrgId.mockResolvedValue(
+                null
+            );
+
+            const result = await getUserFromXFriggHeaders.execute(
+                'app-user-456',
+                'app-org-789'
+            );
+
+            expect(result).toBeInstanceOf(User);
+            // Should not throw conflict error when only one user found
+        });
+
+        it('should handle empty string IDs as falsy', async () => {
+            await expect(
+                getUserFromXFriggHeaders.execute('', '')
+            ).rejects.toThrow();
+        });
+    });
+});
+

package/user/use-cases/authenticate-user.js

@@ -0,0 +1,78 @@
+const Boom = require('@hapi/boom');
+
+/**
+ * Use case for authenticating a user using multiple authentication strategies.
+ * Supports Frigg native tokens, x-frigg headers, and adopter JWT (when implemented).
+ * Tries authentication methods in priority order based on userConfig.authModes.
+ *
+ * @class AuthenticateUser
+ */
+class AuthenticateUser {
+    /**
+     * Creates a new AuthenticateUser instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('./get-user-from-bearer-token').GetUserFromBearerToken} params.getUserFromBearerToken - Use case for bearer token auth.
+     * @param {import('./get-user-from-x-frigg-headers').GetUserFromXFriggHeaders} params.getUserFromXFriggHeaders - Use case for x-frigg header auth.
+     * @param {import('./get-user-from-adopter-jwt').GetUserFromAdopterJwt} params.getUserFromAdopterJwt - Use case for adopter JWT auth.
+     * @param {Object} params.userConfig - The user config in the app definition.
+     */
+    constructor({
+        getUserFromBearerToken,
+        getUserFromXFriggHeaders,
+        getUserFromAdopterJwt,
+        userConfig,
+    }) {
+        this.getUserFromBearerToken = getUserFromBearerToken;
+        this.getUserFromXFriggHeaders = getUserFromXFriggHeaders;
+        this.getUserFromAdopterJwt = getUserFromAdopterJwt;
+        this.userConfig = userConfig;
+    }
+
+    /**
+     * Executes the use case.
+     * @async
+     * @param {Object} req - Express request object with headers.
+     * @returns {Promise<import('../user').User>} The authenticated user object.
+     * @throws {Boom} Unauthorized if no valid authentication provided.
+     */
+    async execute(req) {
+        const authModes = this.userConfig.authModes || { friggToken: true };
+
+        // Priority 1: x-frigg headers (backend-to-backend)
+        if (authModes.xFriggHeaders !== false) {
+            const appUserId = req.headers['x-frigg-appuserid'];
+            const appOrgId = req.headers['x-frigg-apporgid'];
+
+            if (appUserId || appOrgId) {
+                return await this.getUserFromXFriggHeaders.execute(
+                    appUserId,
+                    appOrgId
+                );
+            }
+        }
+
+        // Priority 2: Adopter JWT (if enabled)
+        if (
+            authModes.adopterJwt === true &&
+            req.headers.authorization?.startsWith('Bearer ')
+        ) {
+            const token = req.headers.authorization.split(' ')[1];
+            // Detect JWT format (3 parts separated by dots)
+            if (token && token.split('.').length === 3) {
+                return await this.getUserFromAdopterJwt.execute(token);
+            }
+        }
+
+        // Priority 3: Frigg native token (default)
+        if (authModes.friggToken !== false) {
+            return await this.getUserFromBearerToken.execute(
+                req.headers.authorization
+            );
+        }
+
+        throw Boom.unauthorized('No valid authentication provided');
+    }
+}
+
+module.exports = { AuthenticateUser };
+

package/user/use-cases/get-user-from-adopter-jwt.js

@@ -0,0 +1,148 @@
+const Boom = require('@hapi/boom');
+
+/**
+ * STUB: Use case for retrieving a user from adopter-provided JWT token.
+ *
+ * This is a stub implementation for future JWT authentication support.
+ * When implemented, this will allow adopters to use their own JWT tokens
+ * for authentication instead of Frigg's native token system.
+ *
+ * FUTURE IMPLEMENTATION REQUIREMENTS:
+ * - Validate JWT signature using jwtConfig.secret from app definition
+ * - Support configurable signing algorithms (HS256, HS384, HS512, RS256, RS384, RS512)
+ * - Extract user identifiers from JWT claims based on jwtConfig.userIdClaim and jwtConfig.orgIdClaim
+ * - Find or create user based on extracted claim values
+ * - Handle token expiration and validation errors
+ * - Support refresh tokens (optional)
+ * - Validate user ID conflicts if both individual and org IDs present in JWT
+ *
+ * RECOMMENDED IMPLEMENTATION:
+ * - Use 'jsonwebtoken' package for JWT parsing and validation
+ * - Cache JWT public keys for RS* algorithms
+ * - Add comprehensive error handling for invalid tokens
+ * - Log authentication attempts for security auditing
+ *
+ * @todo Implement JWT validation with jsonwebtoken package
+ * @todo Add unit tests for JWT parsing and claim extraction
+ * @todo Document adopter JWT integration guide in Frigg docs
+ * @todo Add support for JWT refresh tokens
+ * @todo Implement JWT public key caching for RS* algorithms
+ *
+ * @class GetUserFromAdopterJwt
+ */
+class GetUserFromAdopterJwt {
+    /**
+     * Creates a new GetUserFromAdopterJwt instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {Object} params.userConfig - The user config in the app definition.
+     */
+    constructor({ userRepository, userConfig }) {
+        this.userRepository = userRepository;
+        this.userConfig = userConfig;
+    }
+
+    /**
+     * Executes the use case.
+     * @async
+     * @param {string} jwtToken - The JWT token from the Authorization header.
+     * @returns {Promise<import('../user').User>} The authenticated user object.
+     * @throws {Boom} 501 Not Implemented - This feature is not yet available.
+     */
+    async execute(jwtToken) {
+        throw Boom.notImplemented(
+            'Adopter JWT authentication is not yet implemented. ' +
+                'This feature is planned for a future Frigg release. ' +
+                'Please use one of the supported authentication modes instead: ' +
+                'friggToken (native bearer token) or xFriggHeaders (backend-to-backend with x-frigg-appUserId/appOrgId headers).'
+        );
+
+        /* FUTURE IMPLEMENTATION PSEUDOCODE:
+
+        const jwt = require('jsonwebtoken');
+        
+        // Validate JWT configuration exists
+        if (!this.userConfig.jwtConfig || !this.userConfig.jwtConfig.secret) {
+            throw Boom.badImplementation('JWT configuration is required when adopterJwt auth mode is enabled');
+        }
+        
+        try {
+            // Verify and decode JWT
+            const decoded = jwt.verify(jwtToken, this.userConfig.jwtConfig.secret, {
+                algorithms: [this.userConfig.jwtConfig.algorithm || 'HS256']
+            });
+            
+            // Extract user identifiers from claims
+            const appUserId = decoded[this.userConfig.jwtConfig.userIdClaim || 'sub'];
+            const appOrgId = decoded[this.userConfig.jwtConfig.orgIdClaim || 'org_id'];
+            
+            // At least one identifier required
+            if (!appUserId && !appOrgId) {
+                throw Boom.badRequest('JWT must contain user or organization identifier claims');
+            }
+            
+            // Find existing users
+            let individualUserData = null;
+            let organizationUserData = null;
+            
+            if (appUserId) {
+                individualUserData = await this.userRepository.findIndividualUserByAppUserId(appUserId);
+            }
+            
+            if (appOrgId) {
+                organizationUserData = await this.userRepository.findOrganizationUserByAppOrgId(appOrgId);
+            }
+            
+            // Validate no conflicts if both IDs present
+            if (appUserId && appOrgId && individualUserData && organizationUserData) {
+                const individualOrgId = individualUserData.organizationUser?.toString();
+                const expectedOrgId = organizationUserData.id?.toString();
+                
+                if (individualOrgId !== expectedOrgId) {
+                    throw Boom.badRequest(
+                        'User ID mismatch: JWT claims refer to different users. ' +
+                        'Individual and organization IDs must belong to the same user.'
+                    );
+                }
+            }
+            
+            // Auto-create if not found
+            if (!individualUserData && !organizationUserData) {
+                if (appUserId) {
+                    individualUserData = await this.userRepository.createIndividualUser({
+                        appUserId,
+                        username: `jwt-user-${appUserId}`,
+                        email: decoded.email || `${appUserId}@jwt.local`,
+                    });
+                } else {
+                    organizationUserData = await this.userRepository.createOrganizationUser({
+                        appOrgId,
+                    });
+                }
+            }
+            
+            return new User(
+                individualUserData,
+                organizationUserData,
+                this.userConfig.usePassword,
+                this.userConfig.primary,
+                this.userConfig.individualUserRequired,
+                this.userConfig.organizationUserRequired
+            );
+            
+        } catch (error) {
+            if (error.name === 'TokenExpiredError') {
+                throw Boom.unauthorized('JWT token has expired');
+            } else if (error.name === 'JsonWebTokenError') {
+                throw Boom.unauthorized('Invalid JWT token');
+            } else if (error.isBoom) {
+                throw error;
+            }
+            throw Boom.unauthorized('JWT authentication failed');
+        }
+        */
+    }
+}
+
+module.exports = { GetUserFromAdopterJwt };
+

package/user/use-cases/get-user-from-x-frigg-headers.js

@@ -0,0 +1,105 @@
+const Boom = require('@hapi/boom');
+const { User } = require('../user');
+
+/**
+ * Use case for retrieving or creating a user from x-frigg header identifiers.
+ * Supports backend-to-backend API communication using application user IDs.
+ *
+ * @class GetUserFromXFriggHeaders
+ */
+class GetUserFromXFriggHeaders {
+    /**
+     * Creates a new GetUserFromXFriggHeaders instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {Object} params.userConfig - The user config in the app definition.
+     */
+    constructor({ userRepository, userConfig }) {
+        this.userRepository = userRepository;
+        this.userConfig = userConfig;
+    }
+
+    /**
+     * Executes the use case.
+     * @async
+     * @param {string} [appUserId] - The app user ID from x-frigg-appUserId header.
+     * @param {string} [appOrgId] - The app organization ID from x-frigg-appOrgId header.
+     * @returns {Promise<import('../user').User>} The authenticated user object.
+     * @throws {Boom} 400 Bad Request if neither ID is provided or if both IDs are provided but belong to different users.
+     */
+    async execute(appUserId, appOrgId) {
+        // At least one header must be provided
+        if (!appUserId && !appOrgId) {
+            throw Boom.badRequest(
+                'At least one of x-frigg-appUserId or x-frigg-appOrgId headers is required for backend-to-backend authentication'
+            );
+        }
+
+        // Find users by both IDs if both are provided
+        let individualUserData = null;
+        let organizationUserData = null;
+
+        if (appUserId && this.userConfig.individualUserRequired !== false) {
+            individualUserData =
+                await this.userRepository.findIndividualUserByAppUserId(
+                    appUserId
+                );
+        }
+
+        if (appOrgId && this.userConfig.organizationUserRequired) {
+            organizationUserData =
+                await this.userRepository.findOrganizationUserByAppOrgId(
+                    appOrgId
+                );
+        }
+
+        // VALIDATION: If both IDs provided and both users exist, verify they match
+        if (
+            appUserId &&
+            appOrgId &&
+            individualUserData &&
+            organizationUserData
+        ) {
+            // Check if individual user is linked to the org user
+            const individualOrgId =
+                individualUserData.organizationUser?.toString();
+            const expectedOrgId = organizationUserData.id?.toString();
+
+            if (individualOrgId !== expectedOrgId) {
+                throw Boom.badRequest(
+                    'User ID mismatch: x-frigg-appUserId and x-frigg-appOrgId refer to different users. ' +
+                        'Provide only one identifier or ensure they belong to the same user.'
+                );
+            }
+        }
+
+        // Auto-create user if not found
+        if (!individualUserData && !organizationUserData) {
+            if (appUserId) {
+                individualUserData =
+                    await this.userRepository.createIndividualUser({
+                        appUserId,
+                        username: `app-user-${appUserId}`,
+                        email: `${appUserId}@app.local`,
+                    });
+            } else {
+                organizationUserData =
+                    await this.userRepository.createOrganizationUser({
+                        appOrgId,
+                    });
+            }
+        }
+
+        return new User(
+            individualUserData,
+            organizationUserData,
+            this.userConfig.usePassword,
+            this.userConfig.primary,
+            this.userConfig.individualUserRequired,
+            this.userConfig.organizationUserRequired
+        );
+    }
+}
+
+module.exports = { GetUserFromXFriggHeaders };
+