@friggframework/core 2.0.0--canary.548.c8ae0ca.0 → 2.0.0--canary.545.c40eca4.0

package/modules/use-cases/get-module.js

@@ -15,9 +15,10 @@ class GetModule {
      */
     async execute(entityId, userIdOrUser) {
         // Support both userId (backward compatible) and User object (new pattern)
-        const userId = typeof userIdOrUser === 'object' && userIdOrUser?.getId
-            ? userIdOrUser.getId()
-            : userIdOrUser;
+        const userId =
+            typeof userIdOrUser === 'object' && userIdOrUser?.getId
+                ? userIdOrUser.getId()
+                : userIdOrUser;
 
         const entity = await this.moduleRepository.findEntityById(
             entityId,
@@ -31,9 +32,10 @@ class GetModule {
         // Validate entity ownership
         // If User object provided, use ownsUserId to check linked users
         // Otherwise fall back to simple equality check
-        const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
-            : entity.userId?.toString() === userId?.toString();
+        const isOwned =
+            typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
+                ? userIdOrUser.ownsUserId(entity.userId)
+                : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {
             throw new Error(
@@ -43,7 +45,8 @@ class GetModule {
 
         const entityType = entity.moduleName;
         const moduleDefinition = this.moduleDefinitions.find((def) => {
-            const modelName = Module.getEntityModelFromDefinition(def).modelName;
+            const modelName =
+                Module.getEntityModelFromDefinition(def).modelName;
             return entityType === modelName;
         });
 
@@ -67,8 +70,8 @@ class GetModule {
             credential: module.credential,
             externalId: module.entity.externalId,
             userId: module.entity.user.toString(),
-        }
+        };
     }
 }
 
-module.exports = { GetModule };
+module.exports = { GetModule };

package/modules/use-cases/process-authorization-callback.js

@@ -14,7 +14,7 @@ class ProcessAuthorizationCallback {
         this.moduleDefinitions = moduleDefinitions;
     }
 
-    async execute(userId, entityType, params) {
+    async execute(userId, entityType, params, isGlobal = false) {
         const moduleDefinition = this.moduleDefinitions.find((def) => {
             return entityType === def.moduleName;
         });
@@ -70,7 +70,8 @@ class ProcessAuthorizationCallback {
         const persistedEntity = await this.findOrCreateEntity(
             entityDetails,
             entityType,
-            module.credential.id
+            module.credential.id,
+            isGlobal
         );
 
         return {
@@ -93,18 +94,22 @@ class ProcessAuthorizationCallback {
         );
         credentialDetails.details.authIsValid = true;
 
-        const persisted = await this.credentialRepository.upsertCredential(credentialDetails);
+        const persisted = await this.credentialRepository.upsertCredential(
+            credentialDetails
+        );
         module.credential = persisted;
     }
 
-    async findOrCreateEntity(entityDetails, moduleName, credentialId) {
+    async findOrCreateEntity(entityDetails, moduleName, credentialId, isGlobal = false) {
         const { identifiers, details } = entityDetails;
 
         // Support both 'user' and 'userId' field names from module definitions
         // Some modules use 'user' (legacy), others use 'userId' (newer pattern)
         const userId = identifiers.user || identifiers.userId;
 
-        if (!userId) {
+        // For global entities, userId is not required (it will be null)
+        // For user-specific entities, userId must be provided for security
+        if (!isGlobal && !userId) {
             throw new Error(
                 `Module definition for ${moduleName} must return 'user' or 'userId' in identifiers from getEntityDetails(). ` +
                     `Without userId, entity lookup would match across all users (security issue).`
@@ -113,7 +118,7 @@ class ProcessAuthorizationCallback {
 
         const existingEntity = await this.moduleRepository.findEntity({
             externalId: identifiers.externalId,
-            user: userId,
+            user: isGlobal ? null : userId,
             moduleName: moduleName,
         });
 
@@ -126,6 +131,7 @@ class ProcessAuthorizationCallback {
             ...details,
             moduleName: moduleName,
             credential: credentialId,
+            isGlobal,
         });
     }
 }

package/modules/use-cases/process-authorization-step.js

@@ -0,0 +1,160 @@
+/**
+ * Process Authorization Step Use Case
+ * Business logic for processing individual steps in multi-step authorization workflows
+ *
+ * Responsibilities:
+ * - Load and validate authorization session
+ * - Verify step sequence and user ownership
+ * - Delegate to module's step processing logic
+ * - Update session state and persist changes
+ * - Return next step requirements or completion data
+ *
+ * @example
+ * ```javascript
+ * const useCase = new ProcessAuthorizationStepUseCase({
+ *     authSessionRepository: createAuthorizationSessionRepository(),
+ *     moduleDefinitions: [{ moduleName: 'nagaris', definition: NagarisDefinition, apiClass: NagarisApi }]
+ * });
+ *
+ * // Process step 1 (email submission)
+ * const result = await useCase.execute('session-id', 'user123', 1, { email: 'user@example.com' });
+ * // Returns: { nextStep: 2, sessionId, requirements: {...}, message: 'OTP sent to email' }
+ *
+ * // Process step 2 (OTP verification)
+ * const result = await useCase.execute('session-id', 'user123', 2, { email: 'user@example.com', otp: '123456' });
+ * // Returns: { completed: true, authData: {...}, sessionId }
+ * ```
+ */
+class ProcessAuthorizationStepUseCase {
+    /**
+     * @param {Object} params - Dependencies
+     * @param {import('../repositories/authorization-session-repository-interface').AuthorizationSessionRepositoryInterface} params.authSessionRepository - Session repository
+     * @param {Array<Object>} params.moduleDefinitions - Array of module definitions with structure: { moduleName, definition, apiClass }
+     */
+    constructor({ authSessionRepository, moduleDefinitions }) {
+        if (!authSessionRepository) {
+            throw new Error('authSessionRepository is required');
+        }
+        if (!moduleDefinitions || !Array.isArray(moduleDefinitions)) {
+            throw new Error('moduleDefinitions array is required');
+        }
+        this.authSessionRepository = authSessionRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    /**
+     * Process a single step of multi-step authorization
+     *
+     * @param {string} sessionId - Unique session identifier
+     * @param {string} userId - User ID (for security validation)
+     * @param {number} step - Current step number being processed
+     * @param {Object} stepData - Data submitted for this step
+     * @returns {Promise<Object>} Result object with nextStep info or completion data
+     * @throws {Error} If session not found, validation fails, or step processing fails
+     */
+    async execute(sessionId, userId, step, stepData) {
+        // Validate inputs
+        if (!sessionId) {
+            throw new Error('sessionId is required');
+        }
+        if (!userId) {
+            throw new Error('userId is required');
+        }
+        if (!step || step < 1) {
+            throw new Error('step must be >= 1');
+        }
+        if (!stepData || typeof stepData !== 'object') {
+            throw new Error('stepData object is required');
+        }
+
+        // Load session from repository
+        const session = await this.authSessionRepository.findBySessionId(
+            sessionId
+        );
+
+        if (!session) {
+            throw new Error('Authorization session not found or expired');
+        }
+
+        // Security: Verify session belongs to this user
+        if (session.userId !== userId) {
+            throw new Error('Session does not belong to this user');
+        }
+
+        // Verify session hasn't expired (double-check beyond repository filter)
+        if (session.isExpired()) {
+            throw new Error('Authorization session has expired');
+        }
+
+        // Validate step sequence - prevent skipping steps
+        // Allow step 1 to be re-submitted (restart flow), otherwise must be sequential
+        if (session.currentStep !== step && step !== 1) {
+            throw new Error(
+                `Expected step ${session.currentStep}, received step ${step}`
+            );
+        }
+
+        // Find module definition for this entity type
+        const moduleDefinition = this.moduleDefinitions.find(
+            (def) => def.moduleName === session.entityType
+        );
+
+        if (!moduleDefinition) {
+            throw new Error(
+                `Module definition not found: ${session.entityType}`
+            );
+        }
+
+        // Get module's Definition class
+        const ModuleDefinition = moduleDefinition.definition;
+
+        // Validate module supports multi-step auth
+        if (!ModuleDefinition.processAuthorizationStep) {
+            throw new Error(
+                `Module ${session.entityType} does not support multi-step authorization`
+            );
+        }
+
+        // Create API instance for this step
+        const ApiClass = moduleDefinition.apiClass;
+        const api = new ApiClass({ userId });
+
+        // Delegate to module's step processing logic
+        const result = await ModuleDefinition.processAuthorizationStep(
+            api,
+            step,
+            stepData,
+            session.stepData // Pass accumulated data from previous steps
+        );
+
+        // Handle final step completion
+        if (result.completed) {
+            session.markComplete();
+            await this.authSessionRepository.update(session);
+
+            return {
+                completed: true,
+                authData: result.authData,
+                sessionId,
+            };
+        }
+
+        // Handle intermediate step - advance session
+        session.advanceStep(result.stepData || {});
+        await this.authSessionRepository.update(session);
+
+        // Get requirements for next step
+        const nextRequirements =
+            await ModuleDefinition.getAuthRequirementsForStep(result.nextStep);
+
+        return {
+            nextStep: result.nextStep,
+            totalSteps: session.maxSteps,
+            sessionId,
+            requirements: nextRequirements,
+            message: result.message || undefined,
+        };
+    }
+}
+
+module.exports = { ProcessAuthorizationStepUseCase };

package/modules/use-cases/refresh-entity-options.js

@@ -21,9 +21,10 @@ class RefreshEntityOptions {
      */
     async execute(entityId, userIdOrUser, options) {
         // Support both userId (backward compatible) and User object (new pattern)
-        const userId = typeof userIdOrUser === 'object' && userIdOrUser?.getId
-            ? userIdOrUser.getId()
-            : userIdOrUser;
+        const userId =
+            typeof userIdOrUser === 'object' && userIdOrUser?.getId
+                ? userIdOrUser.getId()
+                : userIdOrUser;
 
         const entity = await this.moduleRepository.findEntityById(
             entityId,
@@ -35,9 +36,10 @@ class RefreshEntityOptions {
         }
 
         // Validate entity ownership
-        const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
-            : entity.userId?.toString() === userId?.toString();
+        const isOwned =
+            typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
+                ? userIdOrUser.ownsUserId(entity.userId)
+                : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {
             throw new Error(

package/modules/use-cases/start-authorization-session.js

@@ -0,0 +1,86 @@
+const crypto = require('crypto');
+const {
+    AuthorizationSession,
+} = require('../domain/entities/AuthorizationSession');
+
+/**
+ * Start Authorization Session Use Case
+ * Business logic for initiating multi-step authorization workflows
+ *
+ * Responsibilities:
+ * - Generate unique session identifiers
+ * - Set appropriate session expiration (15 minutes)
+ * - Create and persist new authorization session
+ * - Validate input parameters
+ *
+ * @example
+ * ```javascript
+ * const useCase = new StartAuthorizationSessionUseCase({
+ *     authSessionRepository: createAuthorizationSessionRepository()
+ * });
+ *
+ * const session = await useCase.execute('user123', 'nagaris', 2);
+ * // Returns new AuthorizationSession ready for step 1
+ * ```
+ */
+class StartAuthorizationSessionUseCase {
+    /**
+     * @param {Object} params - Dependencies
+     * @param {import('../repositories/authorization-session-repository-interface').AuthorizationSessionRepositoryInterface} params.authSessionRepository - Session repository
+     */
+    constructor({ authSessionRepository }) {
+        if (!authSessionRepository) {
+            throw new Error('authSessionRepository is required');
+        }
+        this.authSessionRepository = authSessionRepository;
+    }
+
+    /**
+     * Start a new multi-step authorization session
+     *
+     * @param {string} userId - User ID initiating the auth flow
+     * @param {string} entityType - Type of entity being authorized (module name)
+     * @param {number} maxSteps - Total number of steps in the auth flow
+     * @returns {Promise<import('../domain/entities/AuthorizationSession').AuthorizationSession>} Created session
+     * @throws {Error} If validation fails
+     */
+    async execute(userId, entityType, maxSteps) {
+        // Validate inputs
+        if (!userId) {
+            throw new Error('userId is required');
+        }
+        if (!entityType) {
+            throw new Error('entityType is required');
+        }
+        if (!maxSteps || maxSteps < 1) {
+            throw new Error('maxSteps must be >= 1');
+        }
+
+        // Generate cryptographically secure session ID
+        const sessionId = crypto.randomUUID();
+
+        // Set 15 minute expiration (configurable via env in future)
+        const expirationMinutes = parseInt(
+            process.env.AUTH_SESSION_EXPIRY_MINUTES || '15',
+            10
+        );
+        const expiresAt = new Date(Date.now() + expirationMinutes * 60 * 1000);
+
+        // Create domain entity
+        const session = new AuthorizationSession({
+            sessionId,
+            userId,
+            entityType,
+            currentStep: 1,
+            maxSteps,
+            stepData: {},
+            expiresAt,
+            completed: false,
+        });
+
+        // Persist to database
+        return await this.authSessionRepository.create(session);
+    }
+}
+
+module.exports = { StartAuthorizationSessionUseCase };

package/modules/use-cases/test-module-auth.js

@@ -20,9 +20,10 @@ class TestModuleAuth {
      */
     async execute(entityId, userIdOrUser) {
         // Support both userId (backward compatible) and User object (new pattern)
-        const userId = typeof userIdOrUser === 'object' && userIdOrUser?.getId
-            ? userIdOrUser.getId()
-            : userIdOrUser;
+        const userId =
+            typeof userIdOrUser === 'object' && userIdOrUser?.getId
+                ? userIdOrUser.getId()
+                : userIdOrUser;
 
         const entity = await this.moduleRepository.findEntityById(
             entityId,
@@ -34,9 +35,10 @@ class TestModuleAuth {
         }
 
         // Validate entity ownership
-        const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
-            : entity.userId?.toString() === userId?.toString();
+        const isOwned =
+            typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
+                ? userIdOrUser.ownsUserId(entity.userId)
+                : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {
             throw new Error(

package/modules/use-cases/update-module-entity.js

@@ -0,0 +1,27 @@
+/**
+ * UpdateModuleEntity Use Case
+ * Updates a module entity with new data
+ */
+class UpdateModuleEntity {
+    constructor({ moduleRepository }) {
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute(entityId, updates) {
+        const entity = await this.moduleRepository.findEntityById(entityId);
+
+        if (!entity) {
+            throw new Error(`Entity not found: ${entityId}`);
+        }
+
+        // Update the entity using repository method
+        const updatedEntity = await this.moduleRepository.updateEntity(
+            entityId,
+            updates
+        );
+
+        return updatedEntity;
+    }
+}
+
+module.exports = { UpdateModuleEntity };

package/modules/utils/map-module-dto.js

@@ -11,8 +11,8 @@ function mapModuleClassToModuleDTO(moduleInstance) {
         userId: moduleInstance.userId,
         entity: moduleInstance.entity,
         credentialId: moduleInstance.credential?._id?.toString(),
-        type: moduleInstance.getName()
+        type: moduleInstance.getName(),
     };
 }
 
-module.exports = { mapModuleClassToModuleDTO }; 
+module.exports = { mapModuleClassToModuleDTO };