@friggframework/core 2.0.0-next.121 → 2.0.0-next.122

package/CLAUDE.md

@@ -224,7 +224,7 @@ packages/core/
   (`remove-entities-from-integration.js`) refuses to leave a module with no
   entity (`LAST_ENTITY_OF_MODULE`, 409). Re-adding an attached entity or
   removing a detached one changes nothing; a detached entity is not deleted.
-  `integration-repository-entities-parity.test.js` runs every adapter against
+  `integration-repository-entities-parity.db.test.js` runs every adapter against
   real databases when `INTEGRATION_ENTITIES_PARITY_MONGO_URL` /
   `INTEGRATION_ENTITIES_PARITY_POSTGRES_URL` are set. The DocumentDB adapter
   writes only `Integration.entityIds` (as its `createIntegration` does), not
@@ -266,7 +266,7 @@ packages/core/
   mapping keys to leave out of the rows; never write such rows back. Path
   segments must match `^[A-Za-z_][A-Za-z0-9_]*$`. The PostgreSQL, MongoDB and
   DocumentDB adapters give the same pages and totals;
-  `integration-mapping-repository-query-parity.test.js` checks that against
+  `integration-mapping-repository-query-parity.db.test.js` checks that against
   real databases when `QUERY_MAPPINGS_PARITY_MONGO_URL` /
   `QUERY_MAPPINGS_PARITY_POSTGRES_URL` are set. Two orderings still differ:
   strings compare by the database collation on PostgreSQL and by code point

package/application/commands/README.md

@@ -67,9 +67,10 @@ class MyIntegration extends IntegrationBase {
     async hydrateFromExternalUser(externalUserId) {
         // Find integration context by external entity ID
         const result =
-            await this.commands.findIntegrationContextByExternalEntityId(
-                externalUserId
-            );
+            await this.commands.findIntegrationContextByExternalEntityId({
+                externalId: externalUserId,
+                type: 'my-integration', // integration config.type to match
+            });
 
         if (result.error) {
             return { error: result.error };
@@ -231,9 +232,10 @@ Manage integration records and load full integration contexts.
 ```javascript
 // Find integration context by external entity ID
 // Returns { context, error } where context includes record + hydrated modules
-const result = await commands.findIntegrationContextByExternalEntityId(
-    'external-user-or-workspace-id'
-);
+const result = await commands.findIntegrationContextByExternalEntityId({
+    externalId: 'external-user-or-workspace-id',
+    type: 'my-integration', // integration config.type to match
+});
 
 if (!result.error) {
     integration.setIntegrationRecord(result.context);
@@ -299,7 +301,10 @@ try {
 For integration context operations, errors are returned in the result:
 
 ```javascript
-const result = await commands.findIntegrationContextByExternalEntityId(userId);
+const result = await commands.findIntegrationContextByExternalEntityId({
+    externalId: userId,
+    type: 'my-integration',
+});
 
 if (result.error) {
     return { error: result.error };
@@ -349,9 +354,10 @@ const result =
 const { createFriggCommands } = require('@friggframework/core');
 
 this.commands = createFriggCommands({ integrationClass: MyIntegration });
-const result = await this.commands.findIntegrationContextByExternalEntityId(
-    userId
-);
+const result = await this.commands.findIntegrationContextByExternalEntityId({
+    externalId: userId,
+    type: 'my-integration',
+});
 ```
 
 ## Best Practices
@@ -433,7 +439,7 @@ if (!user) {
 |                 | `findEntitiesByIds(ids)`                                | Find multiple by IDs                      |
 |                 | `updateEntity(id, updates)`                             | Update entity properties                  |
 |                 | `deleteEntity(id)`                                      | Delete entity                             |
-| **Integration** | `findIntegrationContextByExternalEntityId(externalId)`  | Load integration + modules by external ID |
+| **Integration** | `findIntegrationContextByExternalEntityId({ externalId, type })` | Load integration + modules by external ID |
 |                 | `loadIntegrationContextById(integrationId)`             | Load integration + modules by ID          |
 
 ## Support

package/database/documentdb-encryption-service.js

@@ -1,4 +1,5 @@
 const { Cryptor } = require('../encrypt/Cryptor');
+const { isEncryptedEnvelope } = require('./encryption/ciphertext-format');
 const {
     getEncryptedFields,
     getFieldsToEncryptOnWrite,
@@ -295,39 +296,7 @@ class DocumentDBEncryptionService {
      * _isEncryptedValue({})  // false
      */
     _isEncryptedValue(value) {
-        // Must be string
-        if (typeof value !== 'string') {
-            return false;
-        }
-
-        // Must have exactly 4 colon-separated parts
-        const parts = value.split(':');
-        if (parts.length !== 4) {
-            return false;
-        }
-
-        // Enhanced validation: check for base64 pattern
-        // This prevents false positives on URLs, connection strings, etc.
-        const base64Pattern = /^[A-Za-z0-9+/=]+$/;
-
-        // All parts should be base64-encoded
-        if (!parts.every(part => base64Pattern.test(part))) {
-            return false;
-        }
-
-        // Encrypted values should be sufficiently long to be valid
-        // Real encrypted values from Cryptor are always >50 chars due to envelope encryption format:
-        // - keyId (base64): ~12 chars minimum
-        // - iv (base64): ~24 chars for 16-byte IV
-        // - ciphertext (base64): varies, minimum ~16 chars for small values
-        // - encryptedKey (base64): ~44 chars for 32-byte data key
-        // Total minimum: ~96 chars, so 50 is a safe lower bound
-        // This prevents false positives on non-encrypted strings that happen to have 4 colons
-        if (value.length < 50) {
-            return false;
-        }
-
-        return true;
+        return isEncryptedEnvelope(value);
     }
 }
 

package/database/encryption/README.md

@@ -508,9 +508,9 @@ return entities.map((e) => ({
 
 **Verified:**
 
--   ✅ `postgres-relation-decryption.test.js` - Proves the bug exists
--   ✅ `postgres-decryption-fix-verification.test.js` - Verifies separate queries work
--   ✅ `mongo-decryption-fix-verification.test.js` - Verifies fix for MongoDB
+-   ✅ `postgres-relation-decryption.db.test.js` - Proves the bug exists
+-   ✅ `postgres-decryption-fix-verification.db.test.js` - Verifies separate queries work
+-   ✅ `mongo-decryption-fix-verification.db.test.js` - Verifies fix for MongoDB
 
 **Implementation Examples:**
 

package/database/encryption/ciphertext-format.js

@@ -0,0 +1,24 @@
+/**
+ * Recognises values produced by Cryptor.encrypt():
+ *   keyId:iv:ciphertext:encryptedKey
+ * keyId and encryptedKey are base64, iv and ciphertext are hex, so all four
+ * parts match the base64 alphabet. Real envelopes are well over 50
+ * characters (the encrypted data key alone is longer).
+ *
+ * Shared by the Prisma (FieldEncryptionService) and DocumentDB paths so a
+ * plaintext value that happens to contain colons (`a:b:c:d`, a URL with
+ * userinfo and a port) is never mistaken for ciphertext: on write it gets
+ * encrypted, on read it is returned as plaintext.
+ */
+const BASE64_PART = /^[A-Za-z0-9+/=]+$/;
+const MIN_ENVELOPE_LENGTH = 50;
+
+function isEncryptedEnvelope(value) {
+    if (typeof value !== 'string' || value.length < MIN_ENVELOPE_LENGTH) {
+        return false;
+    }
+    const parts = value.split(':');
+    return parts.length === 4 && parts.every((part) => BASE64_PART.test(part));
+}
+
+module.exports = { isEncryptedEnvelope };

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

@@ -146,6 +146,16 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
         }
 
         for (const field of credentialFields) {
+            // Validate entry by entry: one bad entry must not drop the
+            // module's (or any other module's) valid fields.
+            if (typeof field !== 'string' || field.trim() === '') {
+                logger.warn(
+                    `Ignoring invalid encryption.credentialFields entry ${JSON.stringify(field)} ` +
+                        `in module "${moduleDef.moduleName || moduleDef.name || 'unknown'}" ` +
+                        '(expected a non-empty string)'
+                );
+                continue;
+            }
             const prefixedField = field.startsWith('data.') ? field : `data.${field}`;
             fields.push(prefixedField);
         }
@@ -174,26 +184,46 @@ function loadModuleEncryptionSchemas(integrations) {
         return;
     }
 
-    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
+    const { getModulesDefinitionFromIntegrationClasses } = require('../../integrations/utils/map-integration-dto');
+
+    // Integrations without modules contribute no credential fields.
+    const integrationsWithModules = integrations.filter(
+        (integration) => integration?.Definition?.modules
+    );
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(
+        integrationsWithModules
+    );
 
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
-    const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
+    // Fields the core schema already encrypts (e.g. data.api_key) are
+    // covered; registering them again would fail validation and drop every
+    // other module field with them.
+    const coreCredentialFields = CORE_ENCRYPTION_SCHEMA.Credential.fields;
+    const credentialFields = extractCredentialFieldsFromModules(
+        moduleDefinitions
+    ).filter((field) => !coreCredentialFields.includes(field));
 
     if (credentialFields.length === 0) {
         return;
     }
 
-    const moduleSchema = {
+    // Merge with whatever custom schema the app already registered rather
+    // than replacing it (registerCustomSchema overwrites).
+    const existingCredentialFields = customSchema.Credential?.fields || [];
+    const mergedSchema = {
+        ...customSchema,
         Credential: {
-            fields: credentialFields
-        }
+            ...customSchema.Credential,
+            fields: [
+                ...new Set([...existingCredentialFields, ...credentialFields]),
+            ],
+        },
     };
 
     logger.info(
         `Registering module-level encryption for ${credentialFields.length} credential fields`
     );
 
-    registerCustomSchema(moduleSchema);
+    registerCustomSchema(mergedSchema);
 }
 
 /**
@@ -205,7 +235,40 @@ function loadModuleEncryptionSchemas(integrations) {
  *
  * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
  */
+/**
+ * Raised when an app's encryption configuration is invalid. In deployed
+ * stages this fails startup instead of silently writing plaintext.
+ */
+class EncryptionSchemaError extends Error {
+    constructor(message, { cause } = {}) {
+        super(message, { cause });
+        this.name = 'EncryptionSchemaError';
+    }
+}
+
+/** Stages where field-level encryption is bypassed (see prisma.js). */
+function isLocalStage() {
+    const stage = process.env.STAGE || process.env.NODE_ENV || 'development';
+    return ['dev', 'test', 'local'].includes(stage.toLowerCase());
+}
+
+/**
+ * An app definition was found but part of its encryption configuration
+ * could not be applied. Deployed stages fail closed; local stages warn and
+ * carry on so development isn't blocked.
+ */
+function reportInvalidEncryptionConfig(what, error) {
+    const message = `Invalid ${what}: ${error.message}`;
+    if (isLocalStage()) {
+        logger.warn(`${message} (ignored in local stage)`);
+        return;
+    }
+    logger.error(message);
+    throw new EncryptionSchemaError(message, { cause: error });
+}
+
 function loadCustomEncryptionSchema() {
+    let appDefinition;
     try {
         // Lazy require to avoid circular dependency issues
         const path = require('node:path');
@@ -220,38 +283,54 @@ function loadCustomEncryptionSchema() {
         const backendIndexPath = path.join(backendDir, 'index.js');
 
         const backendModule = require(backendIndexPath);
-        const appDefinition = backendModule?.Definition;
+        appDefinition = backendModule?.Definition;
+    } catch (error) {
+        // No loadable backend (tests, standalone usage): custom schema is
+        // optional, so this stays at debug level.
+        logger.debug('Could not load custom encryption schema:', error.message);
+        return;
+    }
 
-        if (!appDefinition) {
-            return; // No app definition found
-        }
+    if (!appDefinition) {
+        return; // No app definition found
+    }
+
+    // From here an app definition exists, so failures are configuration
+    // errors and must be visible.
 
-        // Load app-level custom schema
-        const customSchema = appDefinition.encryption?.schema;
-        if (customSchema && Object.keys(customSchema).length > 0) {
+    // Load app-level custom schema
+    const customSchema = appDefinition.encryption?.schema;
+    if (customSchema && Object.keys(customSchema).length > 0) {
+        try {
             registerCustomSchema(customSchema);
+        } catch (error) {
+            reportInvalidEncryptionConfig('app encryption.schema', error);
         }
+    }
 
-        // Load app-level encryption opt-out — apps can declare fields they
-        // don't want encrypted on write (decryption on read still works,
-        // so legacy data remains readable).
-        const disable = appDefinition.encryption?.disable;
-        if (disable && Object.keys(disable).length > 0) {
+    // Load app-level encryption opt-out — apps can declare fields they
+    // don't want encrypted on write (decryption on read still works,
+    // so legacy data remains readable).
+    const disable = appDefinition.encryption?.disable;
+    if (disable && Object.keys(disable).length > 0) {
+        try {
             registerEncryptionOptOut(disable);
+        } catch (error) {
+            reportInvalidEncryptionConfig('app encryption.disable', error);
         }
+    }
 
-        // Load module-level encryption schemas from integrations
-        const integrations = appDefinition.integrations;
-        if (integrations && Array.isArray(integrations)) {
+    // Load module-level encryption schemas from integrations
+    const integrations = appDefinition.integrations;
+    if (integrations && Array.isArray(integrations)) {
+        try {
             loadModuleEncryptionSchemas(integrations);
+        } catch (error) {
+            reportInvalidEncryptionConfig(
+                'module encryption.credentialFields',
+                error
+            );
         }
-    } catch (error) {
-        // Silently ignore errors - custom schema is optional
-        // This handles cases like:
-        // - Backend package.json not found (tests, standalone usage)
-        // - No appDefinition defined
-        // - No custom encryption schema specified
-        logger.debug('Could not load custom encryption schema:', error.message);
     }
 }
 
@@ -386,6 +465,7 @@ function resetCustomSchema() {
 }
 
 module.exports = {
+    EncryptionSchemaError,
     CORE_ENCRYPTION_SCHEMA,
     getEncryptedFields,
     getFieldsToEncryptOnWrite,

package/database/encryption/field-encryption-service.js

@@ -1,3 +1,5 @@
+const { isEncryptedEnvelope } = require('./ciphertext-format');
+
 /**
  * Field Encryption Service
  *
@@ -147,12 +149,7 @@ class FieldEncryptionService {
     }
 
     _isEncrypted(value) {
-        if (typeof value !== 'string') {
-            return false;
-        }
-
-        const parts = value.split(':');
-        return parts.length >= 4;
+        return isEncryptedEnvelope(value);
     }
 
     _getNestedValue(obj, path) {
@@ -218,22 +215,22 @@ class FieldEncryptionService {
     }
 
     /**
-     * Serialize a value for encryption
-     * Objects/arrays are JSON stringified, primitives are converted to strings
+     * Serialize a value for encryption.
+     * Every value is JSON-encoded, strings included, so the type survives
+     * the round trip: '123456' is stored as "\"123456\"" and reads back as a
+     * string, 1234 reads back as a number.
      * @private
      */
     _serializeForEncryption(value) {
-        if (typeof value === 'object' && value !== null) {
-            // JSON.stringify for objects and arrays
-            return JSON.stringify(value);
-        }
-        // For primitives (string, number, boolean), convert to string
-        return String(value);
+        return JSON.stringify(value);
     }
 
     /**
-     * Deserialize a value after decryption
-     * Attempts to parse as JSON, returns string if parsing fails
+     * Deserialize a value after decryption.
+     * Parses the JSON written by _serializeForEncryption. Values encrypted by
+     * earlier versions stored strings raw: those that aren't valid JSON come
+     * back unchanged; a raw legacy string that is also valid JSON (e.g.
+     * '123456') still parses as it always did.
      * @private
      */
     _deserializeAfterDecryption(value) {

package/database/prisma.js

@@ -1,7 +1,10 @@
 const {
     createEncryptionExtension,
 } = require('./encryption/prisma-encryption-extension');
-const { loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
+const {
+    loadCustomEncryptionSchema,
+    EncryptionSchemaError,
+} = require('./encryption/encryption-schema-registry');
 const { logger } = require('./encryption/logger');
 const { Cryptor } = require('../encrypt/Cryptor');
 const config = require('./config');
@@ -125,6 +128,12 @@ const prismaClientSingleton = () => {
                 `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
             );
         } catch (error) {
+            // An invalid encryption configuration must fail startup: carrying
+            // on without the extension would write encrypted fields in
+            // plaintext.
+            if (error instanceof EncryptionSchemaError) {
+                throw error;
+            }
             logger.error(
                 'Failed to initialize encryption extension:',
                 error

package/jest-setup.js

@@ -1,2 +1,13 @@
-const {globalSetup} = require('@friggframework/test');
-module.exports = globalSetup;
+// Core's unit suites must not need a database, so this global setup only
+// sets the test environment. It deliberately does not start an in-memory
+// MongoDB (as @friggframework/test's globalSetup does): nothing in the default
+// suite talks to a live server, and a binary that failed to start used to stop
+// every core suite from running. Suites that need a real database are
+// `*.db.test.js` files, run by `npm run test:db` (see jest.db.config.js).
+const { overrideEnvironment } = require('@friggframework/test');
+
+module.exports = async function () {
+    if (!process.env.STAGE) {
+        overrideEnvironment({ STAGE: 'dev' });
+    }
+};

package/jest-teardown.js

@@ -1,2 +1,5 @@
-const {globalTeardown} = require('@friggframework/test');
-module.exports = globalTeardown;
+const { restoreEnvironment } = require('@friggframework/test');
+
+module.exports = async function () {
+    restoreEnvironment();
+};

package/jest.config.js

@@ -20,4 +20,8 @@ module.exports = {
     globalTeardown: './jest-teardown.js',
 
     setupFilesAfterEnv: ['./logs/jest-logger-setup.js'],
+
+    // `*.db.test.js` suites talk to a real MongoDB replica set / PostgreSQL
+    // and run separately via `npm run test:db` (jest.db.config.js).
+    testPathIgnorePatterns: ['/node_modules/', '\\.db\\.test\\.js$'],
 };

package/jest.db.config.js

@@ -0,0 +1,23 @@
+/*
+ * Database integration suites (`*.db.test.js`).
+ *
+ * These talk to real databases instead of mocking Prisma, so they are kept
+ * out of the default `npm test` run and executed with `npm run test:db`.
+ * They need generated Prisma clients (`npm run prisma:generate`) and:
+ *   - a MongoDB replica set (Prisma requires one for MongoDB writes):
+ *     FRIGG_TEST_MONGODB_URL, default
+ *     mongodb://localhost:27017/frigg?replicaSet=rs0
+ *   - PostgreSQL with the prisma-postgresql migrations applied:
+ *     FRIGG_TEST_POSTGRES_URL, default
+ *     postgresql://postgres:postgres@localhost:5432/frigg?schema=public
+ * The repository parity suites skip themselves unless their own URLs are
+ * set (INTEGRATION_ENTITIES_PARITY_* / QUERY_MAPPINGS_PARITY_*).
+ */
+const base = require('./jest.config');
+
+module.exports = {
+    ...base,
+    coverageThreshold: undefined,
+    testMatch: ['**/*.db.test.js'],
+    testPathIgnorePatterns: ['/node_modules/'],
+};

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.121",
+    "version": "2.0.0-next.122",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.121",
-        "@friggframework/prettier-config": "2.0.0-next.121",
-        "@friggframework/test": "2.0.0-next.121",
+        "@friggframework/eslint-config": "2.0.0-next.122",
+        "@friggframework/prettier-config": "2.0.0-next.122",
+        "@friggframework/test": "2.0.0-next.122",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -68,6 +68,7 @@
     "scripts": {
         "lint:fix": "prettier --write --loglevel error . && eslint . --fix",
         "test": "jest --passWithNoTests # TODO",
+        "test:db": "jest --config jest.db.config.js --runInBand",
         "prisma:generate:mongo": "npx prisma generate --schema ./prisma-mongodb/schema.prisma",
         "prisma:generate:postgres": "npx prisma generate --schema ./prisma-postgresql/schema.prisma",
         "prisma:generate": "npm run prisma:generate:mongo && npm run prisma:generate:postgres",
@@ -90,5 +91,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "311b30a60ef98880ceeede1594375ae2c10347eb"
+    "gitHead": "d9e2755c836c7cfb4f2de7a8e3d003c6d7167d03"
 }

package/queues/queuer-util.js

@@ -97,16 +97,17 @@ const QueuerUtil = {
                 Id: uuid(),
                 MessageBody: JSON.stringify(entry),
             });
-            // Sends 10, then purges the buffer
+            // Sends 10, then starts a fresh buffer. Each command gets its own
+            // array: clearing the shared buffer in place would also empty the
+            // Entries of a command that was already sent.
             if (buffer.length === batchSize) {
+                const batch = buffer.splice(0, buffer.length);
                 const command = new SendMessageBatchCommand({
-                    Entries: buffer,
+                    Entries: batch,
                     QueueUrl: queueUrl,
                 });
                 const result = await sqs.send(command);
-                inspectBatchResult(result, queueUrl, buffer);
-                // Purge the buffer
-                buffer.splice(0, buffer.length);
+                inspectBatchResult(result, queueUrl, batch);
             }
         }