@friggframework/core 2.0.0-next.55 → 2.0.0-next.57

package/credential/repositories/credential-repository-documentdb.js

@@ -106,7 +106,7 @@ class CredentialRepositoryDocumentDB extends CredentialRepositoryInterface {
             const updateDocument = {
                 userId: existing.userId,
                 externalId: existing.externalId,
-                authIsValid: authIsValid,
+                authIsValid: authIsValid !== undefined ? authIsValid : existing.authIsValid,
                 data: mergedData,
                 updatedAt: now,
             };
@@ -143,7 +143,7 @@ class CredentialRepositoryDocumentDB extends CredentialRepositoryInterface {
         }
 
         const plainDocument = {
-            userId: identifiers.userId,
+            userId: toObjectId(identifiers.userId),
             externalId: identifiers.externalId,
             authIsValid: details.authIsValid,
             data: { ...oauthData },
@@ -245,7 +245,7 @@ class CredentialRepositoryDocumentDB extends CredentialRepositoryInterface {
             if (idObj) filter._id = idObj;
         }
         if (identifiers.userId) {
-            filter.userId = identifiers.userId;
+            filter.userId = toObjectId(identifiers.userId);
         }
         if (identifiers.externalId !== undefined) {
             filter.externalId = identifiers.externalId;

package/credential/repositories/credential-repository-mongo.js

@@ -121,7 +121,7 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
                 data: {
                     userId: existing.userId,
                     externalId: existing.externalId,
-                    authIsValid: authIsValid,
+                    authIsValid: authIsValid !== undefined ? authIsValid : existing.authIsValid,
                     data: mergedData,
                 },
             });

package/credential/repositories/credential-repository-postgres.js

@@ -111,7 +111,8 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         if (!identifiers)
             throw new Error('identifiers required to upsert credential');
 
-        if (!identifiers.userId) {
+        // Support both userId (preferred) and user (legacy) for backward compatibility
+        if (!identifiers.userId && !identifiers.user) {
             throw new Error('userId required in identifiers');
         }
         if (!identifiers.externalId) {
@@ -138,7 +139,7 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
                 data: {
                     userId: this._convertId(existing.userId),
                     externalId: existing.externalId,
-                    authIsValid: authIsValid,
+                    authIsValid: authIsValid !== undefined ? authIsValid : existing.authIsValid,
                     data: mergedData,
                 },
             });
@@ -154,7 +155,8 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
 
         const created = await this.prisma.credential.create({
             data: {
-                userId: this._convertId(identifiers.userId),
+                // Use userId from where clause (supports both userId and user fields)
+                userId: where.userId,
                 externalId,
                 authIsValid: authIsValid,
                 data: oauthData,
@@ -257,8 +259,11 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         const where = {};
 
         if (identifiers.id) where.id = this._convertId(identifiers.id);
+        // Support both userId (preferred) and user (legacy) for backward compatibility
         if (identifiers.userId)
             where.userId = this._convertId(identifiers.userId);
+        else if (identifiers.user)
+            where.userId = this._convertId(identifiers.user);
         if (identifiers.externalId) where.externalId = identifiers.externalId;
 
         return where;

package/database/encryption/README.md

@@ -122,34 +122,140 @@ Or simply don't configure any encryption keys. In Production field level encrypt
 
 ## Encrypted Fields
 
-Fields are defined in `encryption-schema-registry.js`:
+Core and custom encrypted fields are defined in `encryption-schema-registry.js`. See that file for the current list of encrypted fields.
 
+**Core fields include**:
+- OAuth tokens: `access_token`, `refresh_token`, `id_token`
+- API keys: `api_key`, `apiKey`, `API_KEY_VALUE`
+- Basic auth: `password`
+- OAuth client credentials: `client_secret`
+
+**Note**: API modules should use `api_key` (snake_case) in their `apiPropertiesToPersist.credential` arrays for consistency with OAuth2Requester and BasicAuthRequester conventions.
+
+### API Module Credential Naming Conventions
+
+When creating API module definitions, use **snake_case** for credential property names to ensure automatic encryption:
+
+**✅ Recommended (automatically encrypted):**
 ```javascript
-const ENCRYPTION_SCHEMA = {
-    Credential: {
-        fields: [
-            'data.access_token', // OAuth access token
-            'data.refresh_token', // OAuth refresh token
-            'data.id_token', // OpenID Connect ID token
-        ],
-    },
-    IntegrationMapping: {
-        fields: ['mapping'], // Complete mapping object
-    },
-    User: {
-        fields: ['hashword'], // Password hash
+// API Module Definition
+const Definition = {
+    requiredAuthMethods: {
+        apiPropertiesToPersist: {
+            // For API key authentication
+            credential: ['api_key'],           // ✅ Automatically encrypted
+            // or for OAuth authentication
+            credential: ['access_token', 'refresh_token'],  // ✅ OAuth - encrypted
+            // or for Basic authentication
+            credential: ['username', 'password'],           // ✅ Basic auth - encrypted
+        }
+    }
+};
+
+// API class (extends ApiKeyRequester)
+class MyApi extends ApiKeyRequester {
+    constructor(params) {
+        super(params);
+        this.api_key = params.api_key;  // ✅ snake_case convention
+    }
+}
+```
+
+**❌ Avoid (requires manual encryption schema):**
+```javascript
+apiPropertiesToPersist: {
+    credential: ['customToken', 'proprietaryKey']  // ❌ Not in core schema
+}
+```
+
+For custom credential fields not in the core schema, use the custom encryption schema feature (see below).
+
+### Extending Encryption Schema
+
+#### Option 1: Module-Level Encryption (API Module Developers)
+
+**NEW**: API modules can now declare their encryption requirements directly in the module definition:
+
+```javascript
+// api-module-library/my-service/definition.js
+const Definition = {
+    moduleName: 'myService',
+    API: MyServiceApi,
+
+    // Declare which credential fields need encryption
+    encryption: {
+        credentialFields: ['api_key', 'webhook_secret']
     },
-    Token: {
-        fields: ['token'], // Authentication token
+
+    requiredAuthMethods: {
+        apiPropertiesToPersist: {
+            credential: ['api_key', 'webhook_secret'],  // These will be auto-encrypted
+            entity: []
+        },
+        // ... other methods
+    }
+};
+```
+
+**How it works**:
+1. Module declares `encryption.credentialFields` array
+2. Framework automatically adds `data.` prefix: `['api_key']` → `['data.api_key']`
+3. Fields are merged with core encryption schema on app startup
+4. All modules across all integrations are scanned and combined
+
+**Benefits**:
+- ✅ Module authors control their own security requirements
+- ✅ No need to modify core framework or app configuration
+- ✅ Automatic encryption for API key-based integrations
+- ✅ Works seamlessly with `apiPropertiesToPersist`
+
+**Example - API Key Module**:
+```javascript
+// API Module Definition
+const Definition = {
+    moduleName: 'axiscare',
+    API: AxisCareApi,
+    encryption: {
+        credentialFields: ['api_key']  // Auto-encrypted as 'data.api_key'
     },
+    requiredAuthMethods: {
+        apiPropertiesToPersist: {
+            credential: ['api_key']  // Will be encrypted automatically
+        }
+    }
 };
+
+// API Class (extends ApiKeyRequester)
+class AxisCareApi extends ApiKeyRequester {
+    constructor(params) {
+        super(params);
+        this.api_key = params.api_key;  // snake_case convention
+    }
+}
 ```
 
-### Extending Encryption Schema
+**Example - Custom Authentication**:
+```javascript
+const Definition = {
+    moduleName: 'customService',
+    encryption: {
+        credentialFields: [
+            'signing_key',
+            'webhook_secret',
+            'data.custom_nested_field'  // Can specify data. prefix explicitly
+        ]
+    }
+};
+```
+
+**Limitations**:
+- Only supports Credential model fields (stored in `credential.data`)
+- Cannot encrypt entity fields or custom models (use app-level schema for those)
+- Applied globally once - module schemas loaded at app startup
 
-#### Recommended: Custom Schema via appDefinition (Integration Developers)
+#### Option 2: App-Level Custom Schema (Integration Developers)
 
-Integration developers can extend encryption without modifying core framework files:
+Integration developers can extend encryption without modifying core framework files.
 
 **In `backend/index.js`:**
 
@@ -234,7 +340,7 @@ await prisma.asanaTaskMapping.create({
 FRIGG_DEBUG=1 npm run frigg:start
 ```
 
-#### Advanced: Modifying Core Schema (Framework Developers)
+#### Option 3: Modifying Core Schema (Framework Developers)
 
 Framework developers maintaining core models can modify `encryption-schema-registry.js`:
 

package/database/encryption/encryption-schema-registry.js

@@ -19,6 +19,11 @@ const CORE_ENCRYPTION_SCHEMA = {
             'data.access_token',
             'data.refresh_token',
             'data.id_token',
+            'data.api_key',
+            'data.apiKey',
+            'data.API_KEY_VALUE',
+            'data.password',
+            'data.client_secret',
         ],
     },
 
@@ -109,6 +114,74 @@ function registerCustomSchema(schema) {
     );
 }
 
+/**
+ * Extracts credential field paths from module definitions
+ * @param {Array} moduleDefinitions - Array of module definition objects
+ * @returns {Array<string>} Array of field paths with data. prefix
+ */
+function extractCredentialFieldsFromModules(moduleDefinitions) {
+    const fields = [];
+
+    for (const moduleDef of moduleDefinitions) {
+        if (!moduleDef?.encryption?.credentialFields) {
+            continue;
+        }
+
+        const credentialFields = moduleDef.encryption.credentialFields;
+        if (!Array.isArray(credentialFields) || credentialFields.length === 0) {
+            continue;
+        }
+
+        for (const field of credentialFields) {
+            const prefixedField = field.startsWith('data.') ? field : `data.${field}`;
+            fields.push(prefixedField);
+        }
+    }
+
+    return [...new Set(fields)];
+}
+
+/**
+ * Loads and registers encryption schemas from API module definitions.
+ * Each module can declare credentialFields to encrypt in its encryption config.
+ *
+ * @param {Array} integrations - Array of integration classes with modules
+ */
+function loadModuleEncryptionSchemas(integrations) {
+    if (!integrations) {
+        throw new Error('integrations parameter is required');
+    }
+
+    if (!Array.isArray(integrations)) {
+        throw new Error('integrations must be an array');
+    }
+
+    if (integrations.length === 0) {
+        return;
+    }
+
+    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
+
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
+    const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
+
+    if (credentialFields.length === 0) {
+        return;
+    }
+
+    const moduleSchema = {
+        Credential: {
+            fields: credentialFields
+        }
+    };
+
+    logger.info(
+        `Registering module-level encryption for ${credentialFields.length} credential fields`
+    );
+
+    registerCustomSchema(moduleSchema);
+}
+
 /**
  * Loads and registers custom encryption schema from appDefinition.
  * Gracefully handles cases where appDefinition is not available.
@@ -139,11 +212,17 @@ function loadCustomEncryptionSchema() {
             return; // No app definition found
         }
 
+        // Load app-level custom schema
         const customSchema = appDefinition.encryption?.schema;
-
         if (customSchema && Object.keys(customSchema).length > 0) {
             registerCustomSchema(customSchema);
         }
+
+        // Load module-level encryption schemas from integrations
+        const integrations = appDefinition.integrations;
+        if (integrations && Array.isArray(integrations)) {
+            loadModuleEncryptionSchemas(integrations);
+        }
     } catch (error) {
         // Silently ignore errors - custom schema is optional
         // This handles cases like:
@@ -182,6 +261,8 @@ module.exports = {
     getEncryptedModels,
     registerCustomSchema,
     loadCustomEncryptionSchema,
+    loadModuleEncryptionSchemas,
+    extractCredentialFieldsFromModules,
     validateCustomSchema,
-    resetCustomSchema, // For testing only
+    resetCustomSchema,
 };

package/database/index.js

@@ -12,13 +12,14 @@
  * etc.
  */
 
-const { mongoose } = require('./mongoose');
-const { IndividualUser } = require('./models/IndividualUser');
-const { OrganizationUser } = require('./models/OrganizationUser');
-const { UserModel } = require('./models/UserModel');
-const { WebsocketConnection } = require('./models/WebsocketConnection');
+// Lazy-load mongoose to avoid importing mongodb when using PostgreSQL only
+let _mongoose = null;
+let _IndividualUser = null;
+let _OrganizationUser = null;
+let _UserModel = null;
+let _WebsocketConnection = null;
 
-// Prisma exports
+// Prisma exports (always available)
 const { prisma } = require('./prisma');
 const { TokenRepository } = require('../token/repositories/token-repository');
 const {
@@ -26,12 +27,38 @@ const {
 } = require('../websocket/repositories/websocket-connection-repository');
 
 module.exports = {
-    mongoose,
-    IndividualUser,
-    OrganizationUser,
-    UserModel,
-    WebsocketConnection,
-    // Prisma
+    // Lazy-loaded mongoose exports (only load when accessed)
+    get mongoose() {
+        if (!_mongoose) {
+            _mongoose = require('./mongoose').mongoose;
+        }
+        return _mongoose;
+    },
+    get IndividualUser() {
+        if (!_IndividualUser) {
+            _IndividualUser = require('./models/IndividualUser').IndividualUser;
+        }
+        return _IndividualUser;
+    },
+    get OrganizationUser() {
+        if (!_OrganizationUser) {
+            _OrganizationUser = require('./models/OrganizationUser').OrganizationUser;
+        }
+        return _OrganizationUser;
+    },
+    get UserModel() {
+        if (!_UserModel) {
+            _UserModel = require('./models/UserModel').UserModel;
+        }
+        return _UserModel;
+    },
+    get WebsocketConnection() {
+        if (!_WebsocketConnection) {
+            _WebsocketConnection = require('./models/WebsocketConnection').WebsocketConnection;
+        }
+        return _WebsocketConnection;
+    },
+    // Prisma (always available)
     prisma,
     TokenRepository,
     WebsocketConnectionRepository,

package/database/utils/prisma-runner.js

@@ -373,6 +373,76 @@ async function runPrismaDbPush(verbose = false, nonInteractive = false) {
     });
 }
 
+/**
+ * Runs Prisma migrate resolve to mark a migration as applied or rolled back
+ * @param {string} migrationName - Name of the migration to resolve (e.g., '20251112195422_update_user_unique_constraints')
+ * @param {'applied'|'rolled-back'} action - Whether to mark as applied or rolled back
+ * @param {boolean} verbose - Enable verbose output
+ * @returns {Promise<Object>} { success: boolean, output?: string, error?: string }
+ */
+async function runPrismaMigrateResolve(migrationName, action = 'applied', verbose = false) {
+    return new Promise((resolve) => {
+        try {
+            const schemaPath = getPrismaSchemaPath('postgresql');
+
+            // Get Prisma binary path (checks multiple locations)
+            const prismaBin = getPrismaBinaryPath();
+
+            // Determine args based on whether we're using direct binary or npx
+            const isDirectBinary = prismaBin !== 'npx prisma';
+            const args = isDirectBinary
+                ? ['migrate', 'resolve', `--${action}`, migrationName, '--schema', schemaPath]
+                : ['prisma', 'migrate', 'resolve', `--${action}`, migrationName, '--schema', schemaPath];
+
+            if (verbose) {
+                const displayCmd = isDirectBinary
+                    ? `${prismaBin} ${args.join(' ')}`
+                    : `npx ${args.join(' ')}`;
+                console.log(chalk.gray(`Running: ${displayCmd}`));
+            }
+
+            // Execute the command (prismaBin might be 'node /path/to/index.js' or 'npx prisma')
+            const [executable, ...executableArgs] = prismaBin.split(' ');
+            const fullArgs = [...executableArgs, ...args];
+
+            const proc = spawn(executable, fullArgs, {
+                stdio: 'inherit',
+                env: {
+                    ...process.env,
+                    PRISMA_HIDE_UPDATE_MESSAGE: '1'
+                }
+            });
+
+            proc.on('error', (error) => {
+                resolve({
+                    success: false,
+                    error: error.message
+                });
+            });
+
+            proc.on('close', (code) => {
+                if (code === 0) {
+                    resolve({
+                        success: true,
+                        output: `Migration ${migrationName} marked as ${action}`
+                    });
+                } else {
+                    resolve({
+                        success: false,
+                        error: `Resolve process exited with code ${code}`
+                    });
+                }
+            });
+
+        } catch (error) {
+            resolve({
+                success: false,
+                error: error.message
+            });
+        }
+    });
+}
+
 /**
  * Determines migration command based on STAGE environment variable
  * @param {string} stage - Stage from CLI option or environment
@@ -401,6 +471,7 @@ module.exports = {
     runPrismaGenerate,
     checkDatabaseState,
     runPrismaMigrate,
+    runPrismaMigrateResolve,
     runPrismaDbPush,
     getMigrationCommand
 };

package/handlers/backend-utils.js

@@ -92,13 +92,16 @@ const loadIntegrationForWebhook = async (integrationId) => {
         integrationId
     );
 
-    return await getIntegrationInstance.execute(
+    const instance = await getIntegrationInstance.execute(
         integrationId,
         integrationRecord.userId
     );
+
+    return instance;
 };
 
 const loadIntegrationForProcess = async (processId, integrationClass) => {
+
     const { processRepository, integrationRepository, moduleRepository } =
         initializeRepositories();
 
@@ -122,10 +125,12 @@ const loadIntegrationForProcess = async (processId, integrationClass) => {
         throw new Error(`Process not found: ${processId}`);
     }
 
-    return await getIntegrationInstance.execute(
+    const instance = await getIntegrationInstance.execute(
         process.integrationId,
         process.userId
     );
+
+    return instance;
 };
 
 const createQueueWorker = (integrationClass) => {
@@ -133,18 +138,19 @@ const createQueueWorker = (integrationClass) => {
         async _run(params, context) {
             try {
                 let integrationInstance;
-                if (
-                    params.event === 'ON_WEBHOOK' &&
-                    params.data?.integrationId
-                ) {
-                    integrationInstance = await loadIntegrationForWebhook(
-                        params.data.integrationId
-                    );
-                } else if (params.data?.processId) {
+
+                // Prioritize processId first (for sync handler compatibility),
+                // then integrationId (for ANY event type that needs hydration),
+                // fallback to unhydrated instance
+                if (params.data?.processId) {
                     integrationInstance = await loadIntegrationForProcess(
                         params.data.processId,
                         integrationClass
                     );
+                } else if (params.data?.integrationId) {
+                    integrationInstance = await loadIntegrationForWebhook(
+                        params.data.integrationId
+                    );
                 } else {
                     // Instantiates a DRY integration class without database records.
                     // There will be cases where we need to use helpers that the api modules can export.

package/handlers/routers/db-migration.js

@@ -235,6 +235,77 @@ router.get(
     })
 );
 
+/**
+ * POST /db-migrate/resolve
+ *
+ * Resolve a failed migration by marking it as applied or rolled back
+ *
+ * Request body:
+ * {
+ *   migrationName: string (e.g., '20251112195422_update_user_unique_constraints'),
+ *   action: 'applied' | 'rolled-back',
+ *   stage: string (optional, defaults to STAGE env var or 'production')
+ * }
+ *
+ * Response (200 OK):
+ * {
+ *   success: true,
+ *   message: string,
+ *   migrationName: string,
+ *   action: string
+ * }
+ */
+router.post(
+    '/db-migrate/resolve',
+    catchAsyncError(async (req, res) => {
+        const { migrationName, action = 'applied' } = req.body;
+
+        console.log(`Migration resolve request: migration=${migrationName}, action=${action}`);
+
+        // Validation
+        if (!migrationName) {
+            return res.status(400).json({
+                success: false,
+                error: 'migrationName is required'
+            });
+        }
+
+        if (!['applied', 'rolled-back'].includes(action)) {
+            return res.status(400).json({
+                success: false,
+                error: 'action must be either "applied" or "rolled-back"'
+            });
+        }
+
+        try {
+            // Import prismaRunner here to avoid circular dependencies
+            const prismaRunner = require('../../database/utils/prisma-runner');
+
+            const result = await prismaRunner.runPrismaMigrateResolve(migrationName, action, true);
+
+            if (!result.success) {
+                return res.status(500).json({
+                    success: false,
+                    error: `Failed to resolve migration: ${result.error}`
+                });
+            }
+
+            res.status(200).json({
+                success: true,
+                message: `Migration ${migrationName} marked as ${action}`,
+                migrationName,
+                action
+            });
+        } catch (error) {
+            console.error('Migration resolve failed:', error);
+            return res.status(500).json({
+                success: false,
+                error: error.message
+            });
+        }
+    })
+);
+
 // Minimal Lambda handler (avoids app-handler-helpers which loads core/index.js → user/**)
 const serverlessHttp = require('serverless-http');
 const express = require('express');
@@ -244,7 +315,7 @@ const app = express();
 app.use(cors());
 app.use(express.json());
 app.use(router);
-app.use((err, req, res, next) => {
+app.use((err, _req, res, _next) => {
     console.error('Migration Router Error:', err);
     res.status(500).json({ message: 'Internal Server Error' });
 });