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

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/modules/requester/api-key.js

@@ -1,4 +1,5 @@
 const { Requester } = require('./requester');
+const { get } = require('../../assertions');
 const { ModuleConstants } = require('../ModuleConstants');
 
 
@@ -9,27 +10,42 @@ class ApiKeyRequester extends Requester {
     constructor(params) {
         super(params);
         this.requesterType = 'apiKey';
-        this.API_KEY_NAME = 'key';
-        this.API_KEY_VALUE = null;
+
+        // Use snake_case convention consistent with OAuth2Requester and BasicAuthRequester
+        this.api_key_name = get(params, 'api_key_name', 'key');
+        this.api_key = get(params, 'api_key', null);
+
+        // Backward compatibility: support old naming convention
+        if (!this.api_key && params.API_KEY_VALUE) {
+            this.api_key = params.API_KEY_VALUE;
+        }
+        if (!this.api_key_name && params.API_KEY_NAME) {
+            this.api_key_name = params.API_KEY_NAME;
+        }
     }
 
     async addAuthHeaders(headers) {
-        if (this.API_KEY_VALUE) {
-            headers[this.API_KEY_NAME] = this.API_KEY_VALUE;
+        if (this.api_key) {
+            headers[this.api_key_name] = this.api_key;
         }
         return headers;
     }
 
     isAuthenticated() {
         return (
-            this.API_KEY_VALUE !== null &&
-            this.API_KEY_VALUE !== undefined &&
-            this.API_KEY_VALUE.trim().length() > 0
+            this.api_key !== null &&
+            this.api_key !== undefined &&
+            typeof this.api_key === 'string' &&
+            this.api_key.trim().length > 0
         );
     }
 
     setApiKey(api_key) {
-        this.API_KEY_VALUE = api_key;
+        this.api_key = api_key;
+    }
+
+    setApiKeyName(api_key_name) {
+        this.api_key_name = api_key_name;
     }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.55",
+    "version": "2.0.0-next.56",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.55",
-        "@friggframework/prettier-config": "2.0.0-next.55",
-        "@friggframework/test": "2.0.0-next.55",
+        "@friggframework/eslint-config": "2.0.0-next.56",
+        "@friggframework/prettier-config": "2.0.0-next.56",
+        "@friggframework/test": "2.0.0-next.56",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "7f86d4b5faaab4de74e6e3676948b62d1e1a5bb1"
+    "gitHead": "5551318d5c45913810a6b03a5ea19c72b5c4cb2f"
 }