@friggframework/core 2.0.0-next.6 → 2.0.0-next.60

package/user/use-cases/create-organization-user.js

@@ -0,0 +1,47 @@
+const { get } = require('../../assertions');
+const { User } = require('../user');
+
+/**
+ * Use case for creating an organization user.
+ * @class CreateOrganizationUser
+ */
+class CreateOrganizationUser {
+    /**
+     * Creates a new CreateOrganizationUser instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {Object} params.userConfig - The user properties inside of the app definition.
+     */
+    constructor({ userRepository, userConfig }) {
+        this.userRepository = userRepository;
+        this.userConfig = userConfig;
+    }
+
+    /**
+     * Executes the use case.
+     * @async
+     * @param {Object} params - The parameters for creating the user.
+     * @returns {Promise<import('../user').User>} The newly created user object.
+     */
+    async execute(params) {
+        const name = get(params, 'name');
+        const appOrgId = get(params, 'appOrgId');
+
+        const organizationUserData =
+            await this.userRepository.createOrganizationUser({
+                name,
+                appOrgId,
+            });
+
+        return new User(
+            null,
+            organizationUserData,
+            this.userConfig.usePassword,
+            this.userConfig.primary,
+            this.userConfig.individualUserRequired,
+            this.userConfig.organizationUserRequired
+        );
+    }
+}
+
+module.exports = { CreateOrganizationUser }; 

package/user/use-cases/create-token-for-user-id.js

@@ -0,0 +1,30 @@
+const crypto = require('crypto');
+
+/**
+ * Use case for creating a token for a user ID.
+ * @class CreateTokenForUserId
+ */
+class CreateTokenForUserId {
+    /**
+     * Creates a new CreateTokenForUserId instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     */
+    constructor({ userRepository }) {
+        this.userRepository = userRepository;
+    }
+
+    /**
+     * Executes the use case.
+     * @async
+     * @param {string} userId - The ID of the user to create a token for.
+     * @param {number} minutes - The number of minutes until the token expires.
+     * @returns {Promise<string>} The user token.
+     */
+    async execute(userId, minutes) {
+        const rawToken = crypto.randomBytes(20).toString('hex');
+        return this.userRepository.createToken(userId, rawToken, minutes);
+    }
+}
+
+module.exports = { CreateTokenForUserId }; 

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

@@ -0,0 +1,149 @@
+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-bearer-token.js

@@ -0,0 +1,77 @@
+const Boom = require('@hapi/boom');
+const { User } = require('../user');
+
+/**
+ * Use case for retrieving a user from a bearer token.
+ * @class GetUserFromBearerToken
+ */
+class GetUserFromBearerToken {
+    /**
+     * Creates a new GetUserFromBearerToken instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../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} bearerToken - The bearer token from the authorization header.
+     * @returns {Promise<import('../user').User>} The authenticated user object.
+     * @throws {Boom} 401 Unauthorized if the token is missing, malformed, or invalid.
+     */
+    async execute(bearerToken) {
+        if (!bearerToken) {
+            throw Boom.unauthorized('Missing Authorization Header');
+        }
+
+        const token = bearerToken.split(' ')[1]?.trim();
+        if (!token) {
+            throw Boom.unauthorized('Invalid Token Format');
+        }
+
+        const sessionToken = await this.userRepository.getSessionToken(token);
+
+        if (!sessionToken) {
+            throw Boom.unauthorized('Session Token Not Found');
+        }
+
+        if (this.userConfig.primary === 'organization') {
+            const organizationUserData = await this.userRepository.findOrganizationUserById(sessionToken.user);
+
+            if (!organizationUserData) {
+                throw Boom.unauthorized('Organization User Not Found');
+            }
+
+            return new User(
+                null,
+                organizationUserData,
+                this.userConfig.usePassword,
+                this.userConfig.primary,
+                this.userConfig.individualUserRequired,
+                this.userConfig.organizationUserRequired
+            );
+        }
+
+        const individualUserData = await this.userRepository.findIndividualUserById(sessionToken.user);
+
+        if (!individualUserData) {
+            throw Boom.unauthorized('Individual User Not Found');
+        }
+
+        return new User(
+            individualUserData,
+            null,
+            this.userConfig.usePassword,
+            this.userConfig.primary,
+            this.userConfig.individualUserRequired,
+            this.userConfig.organizationUserRequired
+        );
+    }
+}
+
+module.exports = { GetUserFromBearerToken }; 

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

@@ -0,0 +1,132 @@
+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/AUTO-LINKING: If both IDs provided and both users exist, handle mismatch
+        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) {
+                // Default behavior: Auto-link disconnected users
+                // Opt-in strict mode: Throw error on mismatch
+                if (this.userConfig.strictUserValidation) {
+                    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-link the users
+                individualUserData = await this.userRepository.linkIndividualToOrganization(
+                    individualUserData.id,
+                    organizationUserData.id
+                );
+            }
+        }
+
+        // Auto-create users independently if they don't exist and are required
+        if (
+            !individualUserData &&
+            appUserId &&
+            this.userConfig.individualUserRequired !== false
+        ) {
+            individualUserData =
+                await this.userRepository.createIndividualUser({
+                    appUserId,
+                    username: `app-user-${appUserId}`,
+                    email: `${appUserId}@app.local`,
+                });
+        }
+
+        if (
+            !organizationUserData &&
+            appOrgId &&
+            this.userConfig.organizationUserRequired
+        ) {
+            organizationUserData =
+                await this.userRepository.createOrganizationUser({
+                    appOrgId,
+                });
+
+            // Link individual user to newly created org user if individual exists
+            if (individualUserData && organizationUserData) {
+                individualUserData = await this.userRepository.linkIndividualToOrganization(
+                    individualUserData.id,
+                    organizationUserData.id
+                );
+            }
+        }
+
+        const user = new User(
+            individualUserData,
+            organizationUserData,
+            this.userConfig.usePassword,
+            this.userConfig.primary,
+            this.userConfig.individualUserRequired,
+            this.userConfig.organizationUserRequired
+        );
+
+        return user;
+    }
+}
+
+module.exports = { GetUserFromXFriggHeaders };

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

@@ -0,0 +1,122 @@
+const Boom = require('@hapi/boom');
+const {
+    RequiredPropertyError,
+} = require('../../errors');
+const { User } = require('../user');
+
+/**
+ * Use case for logging in a user.
+ * @class LoginUser
+ */
+class LoginUser {
+    /**
+     * Creates a new LoginUser instance.
+     * @param {Object} params - Configuration parameters.
+     * @param {import('../user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {Object} params.userConfig - The user properties inside of the app definition.
+     */
+    constructor({ userRepository, userConfig }) {
+        this.userRepository = userRepository;
+        this.userConfig = userConfig;
+    }
+
+    /**
+     * Executes the use case.
+     * @async
+     * @param {Object} userCredentials - The user's credentials for authentication.
+     * @param {string} [userCredentials.username] - The username for authentication.
+     * @param {string} [userCredentials.password] - The password for authentication.
+     * @param {string} [userCredentials.appUserId] - The app user id for authentication if no username and password are provided.
+     * @param {string} [userCredentials.appOrgId] - The app organization id for authentication if no username and password are provided.
+     * @returns {Promise<import('../user').User>} The authenticated user object.
+     */
+    async execute(userCredentials) {
+        const { username, password, appUserId, appOrgId } = userCredentials;
+        if (this.userConfig.individualUserRequired) {
+            if (this.userConfig.usePassword) {
+                if (!username) {
+                    throw new RequiredPropertyError({
+                        parent: this,
+                        key: 'username',
+                    });
+                }
+                if (!password) {
+                    throw new RequiredPropertyError({
+                        parent: this,
+                        key: 'password',
+                    });
+                }
+
+                const individualUserData =
+                    await this.userRepository.findIndividualUserByUsername(
+                        username
+                    );
+
+                if (!individualUserData) {
+                    throw Boom.unauthorized('user not found');
+                }
+
+                const individualUser = new User(
+                    individualUserData,
+                    null,
+                    this.userConfig.usePassword,
+                    this.userConfig.primary,
+                    this.userConfig.individualUserRequired,
+                    this.userConfig.organizationUserRequired
+                );
+
+                if (!(await individualUser.isPasswordValid(password))) {
+                    throw Boom.unauthorized('Incorrect username or password');
+                }
+
+                return individualUser;
+            } else {
+                const individualUserData =
+                    await this.userRepository.findIndividualUserByAppUserId(
+                        appUserId
+                    );
+
+                if (!individualUserData) {
+                    throw Boom.unauthorized('user not found');
+                }
+
+                const individualUser = new User(
+                    individualUserData,
+                    null,
+                    this.userConfig.usePassword,
+                    this.userConfig.primary,
+                    this.userConfig.individualUserRequired,
+                    this.userConfig.organizationUserRequired
+                );
+
+                return individualUser;
+            }
+        }
+
+
+        if (this.userConfig.organizationUserRequired) {
+
+            const organizationUserData =
+                await this.userRepository.findOrganizationUserByAppOrgId(appOrgId);
+
+            if (!organizationUserData) {
+                throw Boom.unauthorized(`org user ${appOrgId} not found`);
+            }
+
+            const organizationUser = new User(
+                null,
+                organizationUserData,
+                this.userConfig.usePassword,
+                this.userConfig.primary,
+                this.userConfig.individualUserRequired,
+                this.userConfig.organizationUserRequired
+            );
+
+            return organizationUser;
+        }
+
+        throw new Error('User configuration must require either individualUserRequired or organizationUserRequired');
+    }
+}
+
+module.exports = { LoginUser }; 

package/user/user.js

@@ -0,0 +1,125 @@
+const bcrypt = require('bcryptjs');
+
+/**
+ * Represents a user in the system. The User class is a domain entity,
+ * @class User
+ */
+class User {
+    /**
+     * Creates a new User instance.
+     * @param {import('../database/models/IndividualUser').IndividualUser} [individualUser=null] - The individual user for the user.
+     * @param {import('../database/models/OrganizationUser').OrganizationUser} [organizationUser=null] - The organization user for the user.
+     * @param {boolean} [usePassword=false] - Whether the user has a password.
+     * @param {string} [primary='individual'] - The primary user type.
+     * @param {boolean} [individualUserRequired=true] - Whether the user is required to have an individual user.
+     * @param {boolean} [organizationUserRequired=false] - Whether the user is required to have an organization user.
+     */
+    constructor(individualUser = null, organizationUser = null, usePassword = false, primary = 'individual', individualUserRequired = true, organizationUserRequired = false) {
+        this.individualUser = individualUser;
+        this.organizationUser = organizationUser;
+        this.usePassword = usePassword;
+
+        this.config = {
+            primary,
+            individualUserRequired,
+            organizationUserRequired,
+        };
+    }
+
+    getPrimaryUser() {
+        if (this.config.primary === 'organization') {
+            return this.organizationUser;
+        }
+        return this.individualUser;
+    }
+
+    getId() {
+        return this.getPrimaryUser()?.id;
+    }
+
+    isPasswordRequired() {
+        return this.usePassword;
+    }
+
+    async isPasswordValid(password) {
+        if (!this.isPasswordRequired()) {
+            return true;
+        }
+
+        return await bcrypt.compare(password, this.getPrimaryUser().hashword);
+    }
+
+    setIndividualUser(individualUser) {
+        this.individualUser = individualUser;
+    }
+
+    setOrganizationUser(organizationUser) {
+        this.organizationUser = organizationUser;
+    }
+
+    isOrganizationUserRequired() {
+        return this.config.organizationUserRequired;
+    }
+
+    isIndividualUserRequired() {
+        return this.config.individualUserRequired;
+    }
+
+    getIndividualUser() {
+        return this.individualUser;
+    }
+
+    getOrganizationUser() {
+        return this.organizationUser;
+    }
+
+    /**
+     * Gets the appUserId from the individual user if present.
+     * @returns {string|null} The app user ID or null
+     */
+    getAppUserId() {
+        return this.individualUser?.appUserId || null;
+    }
+
+    /**
+     * Gets the appOrgId from the organization user if present.
+     * @returns {string|null} The app organization ID or null
+     */
+    getAppOrgId() {
+        return this.organizationUser?.appOrgId || null;
+    }
+
+    /**
+     * Checks if a given userId belongs to this user (either primary or linked).
+     * When primary is 'organization', entities owned by the linked individual user
+     * should still be accessible to the organization.
+     *
+     * @param {string|number} userId - The userId to check
+     * @returns {boolean} True if the userId belongs to this user or their linked user
+     */
+    ownsUserId(userId) {
+        const userIdStr = userId?.toString();
+        const primaryId = this.getPrimaryUser()?.id?.toString();
+        const individualId = this.individualUser?.id?.toString();
+        const organizationId = this.organizationUser?.id?.toString();
+
+        // Check if userId matches primary user
+        if (userIdStr === primaryId) {
+            return true;
+        }
+
+        // When primary is 'organization', also check linked individual user
+        if (this.config.primary === 'organization' && userIdStr === individualId) {
+            return true;
+        }
+
+        // When primary is 'individual', also check linked organization user if required
+        if (this.config.primary === 'individual' && this.config.organizationUserRequired && userIdStr === organizationId) {
+            return true;
+        }
+
+        return false;
+    }
+}
+
+module.exports = { User };