@friggframework/core 2.0.0-next.54 → 2.0.0-next.56

package/credential/use-cases/get-credential-for-user.js

@@ -4,14 +4,18 @@ class GetCredentialForUser {
     }
 
     async execute(credentialId, userId) {
-        const credential = await this.credentialRepository.findCredentialById(credentialId);
+        const credential = await this.credentialRepository.findCredentialById(
+            credentialId
+        );
 
         if (!credential) {
             throw new Error(`Credential with id ${credentialId} not found`);
         }
 
-        if (credential.user.toString() !== userId.toString()) {
-            throw new Error(`Credential ${credentialId} does not belong to user ${userId}`);
+        if (credential.userId.toString() !== userId.toString()) {
+            throw new Error(
+                `Credential ${credentialId} does not belong to user ${userId}`
+            );
         }
 
         return credential;

package/database/encryption/README.md

@@ -122,35 +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.domain', // Service domain
-            '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`:**
 
@@ -235,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/errors/client-safe-error.js

@@ -0,0 +1,26 @@
+const { BaseError } = require('./base-error');
+
+/**
+ * ClientSafeError - An error that is safe to expose to end users
+ *
+ * Use this error class when the error message does not contain sensitive
+ * implementation details and can be safely shown to users.
+ *
+ * Examples:
+ * - "Invalid Token: Token is expired"
+ * - "User not found"
+ * - "Invalid credentials"
+ *
+ * @param {string} message - The user-safe error message
+ * @param {number} statusCode - HTTP status code (default: 400)
+ * @param {object} options - Additional error options (cause, etc.)
+ */
+class ClientSafeError extends BaseError {
+    constructor(message, statusCode = 400, options) {
+        super(message, options);
+        this.statusCode = statusCode;
+        this.isClientSafe = true;
+    }
+}
+
+module.exports = { ClientSafeError };

package/errors/fetch-error.js

@@ -61,8 +61,9 @@ class FetchError extends BaseError {
         ];
 
         super(messageParts.filter(Boolean).join('\n'));
-        
+
         this.response = response;
+        this.statusCode = response?.status;
     }
 
     static async create(options = {}) {

package/errors/index.js

@@ -5,6 +5,7 @@ const {
     RequiredPropertyError,
     ParameterTypeError,
 } = require('./validation-errors');
+const { ClientSafeError } = require('./client-safe-error');
 
 module.exports = {
     BaseError,
@@ -12,4 +13,5 @@ module.exports = {
     HaltError,
     RequiredPropertyError,
     ParameterTypeError,
+    ClientSafeError,
 };

package/integrations/integration-router.js

@@ -65,9 +65,7 @@ const {
 const {
     AuthenticateWithSharedSecret,
 } = require('../user/use-cases/authenticate-with-shared-secret');
-const {
-    AuthenticateUser,
-} = require('../user/use-cases/authenticate-user');
+const { AuthenticateUser } = require('../user/use-cases/authenticate-user');
 const {
     ProcessAuthorizationCallback,
 } = require('../modules/use-cases/process-authorization-callback');
@@ -234,8 +232,10 @@ function checkRequiredParams(params, requiredKeys) {
 
     if (missingKeys.length > 0) {
         throw Boom.badRequest(
-            `Missing Parameter${missingKeys.length === 1 ? '' : 's'
-            }: ${missingKeys.join(', ')} ${missingKeys.length === 1 ? 'is' : 'are'
+            `Missing Parameter${
+                missingKeys.length === 1 ? '' : 's'
+            }: ${missingKeys.join(', ')} ${
+                missingKeys.length === 1 ? 'is' : 'are'
             } required.`
         );
     }
@@ -584,7 +584,7 @@ function setEntityRoutes(router, authenticateUser, useCases) {
                 req.params.credentialId,
                 userId
             );
-            if (credential.user._id.toString() !== userId) {
+            if (credential.userId.toString() !== userId) {
                 throw Boom.forbidden('Credential does not belong to user');
             }