@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

package/database/config.js

@@ -3,6 +3,39 @@
  * Manages configuration for Prisma ORM operations
  */
 
+/**
+ * Maps an app definition's `database` block to a Prisma database type.
+ *
+ * @param {Object|undefined} database - `Definition.database`
+ * @param {string} where - where the definition lives, for the error message
+ * @returns {'mongodb'|'postgresql'|'documentdb'}
+ */
+function databaseTypeFromConfig(database, where) {
+    if (!database) {
+        throw new Error(
+            '[Frigg] App definition missing database configuration. ' +
+            `Add database: { postgres: { enable: true } } (or mongoDB/documentDB) to ${where}`
+        );
+    }
+
+    // Determine database type from enabled database
+    // Priority order: postgres > mongoDB > documentDB
+    if (database.postgres?.enable === true) {
+        return 'postgresql';
+    }
+    if (database.mongoDB?.enable === true) {
+        return 'mongodb';
+    }
+    if (database.documentDB?.enable === true) {
+        return 'documentdb';
+    }
+
+    throw new Error(
+        '[Frigg] No database enabled in app definition. ' +
+        'Set one of: database.postgres.enable, database.mongoDB.enable, or database.documentDB.enable to true'
+    );
+}
+
 /**
  * Determines database type from environment or app definition
  * 
@@ -21,6 +54,20 @@ function getDatabaseType() {
 
     // Fallback: Load app definition
     try {
+        // A definition preset with setAppDefinition() (provider-netlify's
+        // function preamble) wins: on Netlify process.cwd() is the function
+        // root at runtime, so discovery cannot find the backend.
+        const {
+            getPresetAppDefinition,
+        } = require('../handlers/app-definition-loader');
+        const preset = getPresetAppDefinition();
+        if (preset) {
+            return databaseTypeFromConfig(
+                preset.database,
+                'your backend/index.js'
+            );
+        }
+
         const path = require('node:path');
         const fs = require('node:fs');
         const { findNearestBackendPackageJson } = require('../utils');
@@ -76,30 +123,7 @@ function getDatabaseType() {
         }
 
         database = backendModule?.Definition?.database;
-
-        if (!database) {
-            throw new Error(
-                '[Frigg] App definition missing database configuration. ' +
-                `Add database: { postgres: { enable: true } } (or mongoDB/documentDB) to ${backendIndexPath}`
-            );
-        }
-
-        // Determine database type from enabled database
-        // Priority order: postgres > mongoDB > documentDB
-        if (database.postgres?.enable === true) {
-            return 'postgresql';
-        }
-        if (database.mongoDB?.enable === true) {
-            return 'mongodb';
-        }
-        if (database.documentDB?.enable === true) {
-            return 'documentdb';
-        }
-
-        throw new Error(
-            '[Frigg] No database enabled in app definition. ' +
-            'Set one of: database.postgres.enable, database.mongoDB.enable, or database.documentDB.enable to true'
-        );
+        return databaseTypeFromConfig(database, backendIndexPath);
     } catch (error) {
         // Re-throw with context if it's our error
         if (error.message.includes('[Frigg]')) {

package/database/documentdb-utils.js

@@ -58,7 +58,12 @@ async function insertOne(client, collection, document) {
 
         // Provide helpful context for common errors
         if (error.code === 11000) {
-            throw new Error(`${errorMsg} - Duplicate key violation`);
+            // `code` lets callers recognise a lost race without parsing text
+            // (see database/unique-violation.js).
+            throw Object.assign(
+                new Error(`${errorMsg} - Duplicate key violation`),
+                { code: 11000 }
+            );
         }
         throw new Error(errorMsg);
     }

package/database/encryption/README.md

@@ -456,8 +456,6 @@ Format: "keyId:encryptedText:encryptedKey"
 Example: "base64KeyId:iv:ciphertext:base64EncryptedDataKey"
 ```
 
-**Recognising ciphertext on read.** A value is decrypted only when it has exactly four colon-separated parts: base64 `keyId`, 32-hex-character `iv`, hex ciphertext, base64 `encryptedKey`. Plaintext that merely contains colons (`https://user:pw@host:443`) is left alone. A value with that shape that still fails to decrypt (a wrong, rotated or missing key) fails the read with `FieldDecryptionError` in a deployed runtime (see [When Encryption Runs](#when-encryption-runs)), so ciphertext never reaches an API module as if it were a token. Locally it is returned as stored and logged as a warning, so one bad field does not fail a whole read. A field that becomes encrypted later (for example a module's `credentialFields`) stays plaintext in existing rows until they are next written.
-
 **Why Envelope Encryption?**
 
 -   Reduces KMS API calls (one DEK per field, cached)

package/database/encryption/encryption-config.js

@@ -18,6 +18,9 @@
  */
 
 const { logger } = require('./logger');
+const {
+    isDeployedRuntime: isDeployedProviderRuntime,
+} = require('../../providers/runtime-detection');
 
 const LOCAL_BYPASS_STAGES = ['dev', 'test', 'local'];
 const OPT_OUT_VAR = 'FRIGG_ENCRYPTION_DISABLED';
@@ -40,42 +43,18 @@ function isTrue(value) {
 }
 
 /**
- * True when the process runs as a deployed function, on AWS Lambda or on
- * another provider's platform.
- *
- * - AWS Lambda sets AWS_LAMBDA_FUNCTION_NAME, LAMBDA_TASK_ROOT and
- *   AWS_EXECUTION_ENV (AWS_Lambda_<runtime>). Other AWS hosts (CloudShell,
- *   CodeBuild, ECS) set AWS_EXECUTION_ENV to other values and count as local:
- *   CLI commands run from CI must not trip the deployed-stage check.
- * - Other providers: FRIGG_PROVIDER names a non-AWS provider. Frigg's
- *   generated function entry points for that provider set it (provider-netlify
- *   sets 'netlify'), so it is present in every deployed function. Netlify
- *   exposes SITE_ID, CONTEXT and NETLIFY at build time only, so they cannot
- *   tell a running function from a laptop.
- *
- * A local run is never deployed: serverless-offline and `serverless invoke
- * local` (which set the Lambda variables themselves) mark IS_OFFLINE /
- * IS_LOCAL, `netlify dev` marks NETLIFY_DEV, and Jest marks JEST_WORKER_ID.
+ * True when the process runs as a deployed function, on AWS Lambda or on the
+ * active provider's platform (provider-netlify: FRIGG_PROVIDER=netlify, set by
+ * its generated entry points), and not under a local emulator or test runner.
+ * One rule for encryption and queue authentication: core/providers/
+ * runtime-detection asks the provider's detect(), and fails closed when a
+ * named non-AWS provider cannot be loaded.
  *
  * @param {Object} [env=process.env]
  * @returns {boolean}
  */
 function isDeployedRuntime(env = process.env) {
-    const localRun =
-        isTrue(env.IS_OFFLINE) ||
-        isTrue(env.IS_LOCAL) ||
-        isTrue(env.NETLIFY_DEV) ||
-        isSet(env.JEST_WORKER_ID);
-    if (localRun) return false;
-
-    const onAwsRuntime =
-        isSet(env.AWS_LAMBDA_FUNCTION_NAME) ||
-        isSet(env.LAMBDA_TASK_ROOT) ||
-        String(env.AWS_EXECUTION_ENV ?? '').startsWith('AWS_Lambda_');
-    if (onAwsRuntime) return true;
-
-    const provider = String(env.FRIGG_PROVIDER ?? '').trim().toLowerCase();
-    return provider !== '' && provider !== 'aws';
+    return isDeployedProviderRuntime(env);
 }
 
 function missingKeyMessage(stage) {

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

@@ -10,11 +10,6 @@
 
 const { logger } = require('./logger');
 const { registerDeniedKeys } = require('../../logs/denied-keys');
-const {
-    getEntityTypeRegistry,
-    getEntityTypeDefinitions,
-    EntityRegistryError,
-} = require('../../modules/entity-type-registry');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -171,9 +166,8 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
  * Each module can declare credentialFields to encrypt in its encryption config.
  *
  * @param {Array} integrations - Array of integration classes with modules
- * @param {object} [entities] - `appDefinition.entities` (ADR-059 registry)
  */
-function loadModuleEncryptionSchemas(integrations, entities) {
+function loadModuleEncryptionSchemas(integrations) {
     if (!integrations) {
         throw new Error('integrations parameter is required');
     }
@@ -182,39 +176,34 @@ function loadModuleEncryptionSchemas(integrations, entities) {
         throw new Error('integrations must be an array');
     }
 
-    // `entities` is the app definition's registry (ADR-059): a module an app
-    // registers without any integration still carries credentials to encrypt.
-    if (integrations.length === 0 && !entities) {
+    if (integrations.length === 0) {
         return;
     }
 
-    const moduleDefinitions = getEntityTypeDefinitions(
-        getEntityTypeRegistry({ integrations, entities })
-    );
+    // NOTE: this path does not exist ('../integrations' resolves to
+    // database/integrations), so today this function throws MODULE_NOT_FOUND,
+    // loadCustomEncryptionSchema swallows it, and module credentialFields are
+    // effectively NOT registered. Fixing it changes which fields are encrypted
+    // and needs a decrypt that tolerates plaintext, so it ships separately:
+    // branch claude/internal-mcp-03b-module-credential-encryption. Left as is
+    // here on purpose (ADR-059 must not change what gets encrypted).
+    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
+
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
     const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
 
-    // Core fields are encrypted already and a custom schema may not repeat
-    // them. Everything the app registered itself stays: module fields are added
-    // to the custom schema, never substituted for it (other models included).
-    const coreFields = new Set(CORE_ENCRYPTION_SCHEMA.Credential?.fields || []);
-    const fields = [
-        ...new Set([
-            ...(customSchema.Credential?.fields || []),
-            ...credentialFields.filter((field) => !coreFields.has(field)),
-        ]),
-    ];
-
-    if (fields.length === 0) {
+    if (credentialFields.length === 0) {
         return;
     }
 
     const moduleSchema = {
-        ...customSchema,
-        Credential: { ...customSchema.Credential, fields },
+        Credential: {
+            fields: credentialFields
+        }
     };
 
     logger.info(
-        `Registering module-level encryption for ${fields.length} credential fields`
+        `Registering module-level encryption for ${credentialFields.length} credential fields`
     );
 
     registerCustomSchema(moduleSchema);
@@ -229,22 +218,80 @@ function loadModuleEncryptionSchemas(integrations, entities) {
  *
  * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
  */
-function loadCustomEncryptionSchema() {
-    try {
-        // Lazy require to avoid circular dependency issues
-        const path = require('node:path');
-        const { findNearestBackendPackageJson } = require('../../utils');
+/**
+ * Registers encryption schemas declared by app-level extensions
+ * (`appDefinition.coreExtensions[].encryption`), e.g. the db-credentials
+ * extension's `OAuthAppCredential.clientSecret`.
+ *
+ * @param {Array<Object>} extensions - Normalized extensions (extension-loader)
+ */
+function loadExtensionEncryptionSchemas(extensions) {
+    if (!extensions || !Array.isArray(extensions) || extensions.length === 0) {
+        return;
+    }
+
+    for (const ext of extensions) {
+        if (!ext.encryption || typeof ext.encryption !== 'object') {
+            continue;
+        }
+
+        const schema = {};
+        for (const [modelName, config] of Object.entries(ext.encryption)) {
+            if (config && Array.isArray(config.fields) && config.fields.length > 0) {
+                schema[modelName] = { fields: config.fields };
+            }
+        }
 
-        const backendPackagePath = findNearestBackendPackageJson();
-        if (!backendPackagePath) {
-            return; // No backend found, skip custom schema
+        if (Object.keys(schema).length > 0) {
+            logger.info(
+                `Registering encryption schema from extension "${ext.name}" for models: ${Object.keys(schema).join(', ')}`
+            );
+            // registerCustomSchema replaces the registered schema, so merge:
+            // an extension adds its models to the app's encryption.schema
+            // rather than dropping it.
+            const merged = { ...customSchema };
+            for (const [modelName, config] of Object.entries(schema)) {
+                const existing = merged[modelName]?.fields || [];
+                merged[modelName] = {
+                    ...merged[modelName],
+                    fields: [...new Set([...existing, ...config.fields])],
+                };
+            }
+            registerCustomSchema(merged);
         }
+    }
+}
+
+function readAppDefinitionForEncryption() {
+    // Lazy require to avoid circular dependency issues
+    const {
+        getPresetAppDefinition,
+    } = require('../../handlers/app-definition-loader');
+    // A definition preset with setAppDefinition() (provider-netlify's
+    // preamble) wins: on Netlify process.cwd() cannot find the backend.
+    const preset = getPresetAppDefinition();
+    if (preset) {
+        return preset;
+    }
+
+    const path = require('node:path');
+    const { findNearestBackendPackageJson } = require('../../utils');
+
+    const backendPackagePath = findNearestBackendPackageJson();
+    if (!backendPackagePath) {
+        return null; // No backend found, skip custom schema
+    }
+
+    const backendDir = path.dirname(backendPackagePath);
+    const backendIndexPath = path.join(backendDir, 'index.js');
 
-        const backendDir = path.dirname(backendPackagePath);
-        const backendIndexPath = path.join(backendDir, 'index.js');
+    const backendModule = require(backendIndexPath);
+    return backendModule?.Definition || null;
+}
 
-        const backendModule = require(backendIndexPath);
-        const appDefinition = backendModule?.Definition;
+function loadCustomEncryptionSchema() {
+    try {
+        const appDefinition = readAppDefinitionForEncryption();
 
         if (!appDefinition) {
             return; // No app definition found
@@ -264,17 +311,21 @@ function loadCustomEncryptionSchema() {
             registerEncryptionOptOut(disable);
         }
 
+        // Load app-level extension encryption schemas. Before the module
+        // schemas: loadModuleEncryptionSchemas currently throws (see the
+        // NOTE inside it) and the throw would skip anything after it.
+        const { loadExtensions } = require('../../extensions/extension-loader');
+        const extensions = loadExtensions(appDefinition);
+        if (extensions.length > 0) {
+            loadExtensionEncryptionSchemas(extensions);
+        }
+
         // Load module-level encryption schemas from integrations
         const integrations = appDefinition.integrations;
-        if (Array.isArray(integrations) || appDefinition.entities) {
-            loadModuleEncryptionSchemas(
-                Array.isArray(integrations) ? integrations : [],
-                appDefinition.entities
-            );
+        if (integrations && Array.isArray(integrations)) {
+            loadModuleEncryptionSchemas(integrations);
         }
     } catch (error) {
-        // A bad entity registry is a configuration error, not "no custom schema".
-        if (error instanceof EntityRegistryError) throw error;
         // Silently ignore errors - custom schema is optional
         // This handles cases like:
         // - Backend package.json not found (tests, standalone usage)
@@ -425,6 +476,7 @@ module.exports = {
     registerEncryptionOptOut,
     loadCustomEncryptionSchema,
     loadModuleEncryptionSchemas,
+    loadExtensionEncryptionSchemas,
     extractCredentialFieldsFromModules,
     validateCustomSchema,
     validateOptOut,

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

@@ -4,41 +4,8 @@
  * Infrastructure layer service that orchestrates field-level encryption/decryption.
  * Handles nested JSON paths (e.g., 'data.access_token') and bulk operations.
  */
-const { logger } = require('./logger');
-const { isDeployedRuntime } = require('./encryption-config');
-
-/**
- * Thrown when a value that looks like ciphertext cannot be decrypted in a
- * deployed runtime (a wrong, rotated or missing key). Returning the stored
- * ciphertext would hand it to API modules as if it were a token.
- */
-class FieldDecryptionError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = 'FieldDecryptionError';
-    }
-}
-
-// Cryptor.encrypt() returns `${keyId}:${iv}:${ciphertext}:${encryptedKey}`:
-// keyId and encryptedKey are base64, iv is 16 bytes of hex, ciphertext is hex.
-// Plaintext with three colons (`https://user:pw@host:443`, `a:b:c:d`) must not
-// be mistaken for it.
-const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/;
-const IV_PART = /^[0-9a-f]{32}$/i;
-const CIPHERTEXT_PART = /^(?:[0-9a-f]{2})+$/i;
-
 class FieldEncryptionService {
-    /**
-     * @param {Object} params
-     * @param {Object} params.cryptor
-     * @param {Object} params.schema
-     * @param {() => boolean} [params.failClosedOnDecryptError] - whether a
-     *   ciphertext-shaped value that fails to decrypt throws. Defaults to
-     *   "running deployed" (encryption-config's isDeployedRuntime), read on
-     *   each failure. Locally such a value is returned as stored, with a
-     *   warning.
-     */
-    constructor({ cryptor, schema, failClosedOnDecryptError }) {
+    constructor({ cryptor, schema }) {
         if (!cryptor) {
             throw new Error('Cryptor instance required');
         }
@@ -48,10 +15,6 @@ class FieldEncryptionService {
 
         this.cryptor = cryptor;
         this.schema = schema;
-        this.failClosedOnDecryptError =
-            typeof failClosedOnDecryptError === 'function'
-                ? failClosedOnDecryptError
-                : () => isDeployedRuntime();
     }
 
     /**
@@ -134,33 +97,12 @@ class FieldEncryptionService {
         const decryptionPromises = fields.map(async (fieldPath) => {
             const value = this._getNestedValue(decrypted, fieldPath);
 
-            if (!this._isEncrypted(value)) {
-                return null;
-            }
-            try {
+            if (this._isEncrypted(value)) {
                 const decryptedValue = await this.cryptor.decrypt(value);
                 const deserializedValue = this._deserializeAfterDecryption(decryptedValue);
                 return { fieldPath, decryptedValue: deserializedValue };
-            } catch (error) {
-                // Deployed: a ciphertext-shaped value under a wrong, rotated or
-                // missing key fails the read rather than reaching an API
-                // module as a token. Legacy plaintext never gets here: it does
-                // not look like ciphertext (_isEncrypted).
-                if (this.failClosedOnDecryptError()) {
-                    throw new FieldDecryptionError(
-                        `Could not decrypt ${modelName}.${fieldPath}`,
-                        { cause: error }
-                    );
-                }
-                // Local: a value that looks like ciphertext but is not is read
-                // as it is stored. One such field must not fail the whole
-                // read, findMany included.
-                logger.warn(
-                    `Could not decrypt ${modelName}.${fieldPath}; returning the stored value`,
-                    { errorName: error?.name }
-                );
-                return null;
             }
+            return null;
         });
 
         const results = await Promise.all(decryptionPromises);
@@ -210,13 +152,7 @@ class FieldEncryptionService {
         }
 
         const parts = value.split(':');
-        return (
-            parts.length === 4 &&
-            BASE64_PART.test(parts[0]) &&
-            IV_PART.test(parts[1]) &&
-            CIPHERTEXT_PART.test(parts[2]) &&
-            BASE64_PART.test(parts[3])
-        );
+        return parts.length >= 4;
     }
 
     _getNestedValue(obj, path) {
@@ -315,4 +251,4 @@ class FieldEncryptionService {
     }
 }
 
-module.exports = { FieldEncryptionService, FieldDecryptionError };
+module.exports = { FieldEncryptionService };

package/database/organization-where.js

@@ -0,0 +1,18 @@
+/**
+ * The Prisma `where` fragment for an `organizationId` on MongoDB (ADR-056
+ * §3.6), shared by the entity and integration adapters.
+ *
+ * Prisma on MongoDB: `null` matches only an explicit null and `isSet: false`
+ * only a missing field. A row written before the column existed is the common
+ * "no organization" case, so `null` here means both.
+ */
+function organizationWhere(organizationId) {
+    if (organizationId === null) {
+        return {
+            OR: [{ organizationId: null }, { organizationId: { isSet: false } }],
+        };
+    }
+    return { organizationId };
+}
+
+module.exports = { organizationWhere };

package/database/prisma.js

@@ -41,13 +41,15 @@ const prismaClientSingleton = () => {
         const paths = [
             // Lambda layer location (when using Prisma Lambda layer)
             `/opt/nodejs/node_modules/generated/prisma-${dbType}`,
+            // __dirname-based absolute path (Netlify functions and bundlers)
+            require('node:path').resolve(__dirname, `../generated/prisma-${dbType}`),
             // Local development location (relative to core package)
             `../generated/prisma-${dbType}`,
         ];
 
-        for (const path of paths) {
+        for (const candidate of paths) {
             try {
-                return require(path).PrismaClient;
+                return require(candidate).PrismaClient;
             } catch (err) {
                 // Continue to next path
             }

package/database/unique-violation.js

@@ -0,0 +1,25 @@
+/** Mongo/DocumentDB duplicate-key error code. */
+const DUPLICATE_KEY_CODE = 11000;
+/** Prisma's unique-constraint error code (PostgreSQL and MongoDB). */
+const PRISMA_UNIQUE_CODE = 'P2002';
+
+/**
+ * Whether `error` is a unique-constraint violation, however the database
+ * layer raised it: a Prisma `P2002`, or a duplicate-key `11000`
+ * (`documentdb-utils` `insertOne` sets `code` on the error it throws).
+ * Matches on the code only, never on message text.
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isUniqueViolation(error) {
+    return (
+        error?.code === PRISMA_UNIQUE_CODE || error?.code === DUPLICATE_KEY_CODE
+    );
+}
+
+module.exports = {
+    isUniqueViolation,
+    DUPLICATE_KEY_CODE,
+    PRISMA_UNIQUE_CODE,
+};

package/extensions/bootstrap-runner.js

@@ -0,0 +1,43 @@
+/**
+ * Bootstrap Runner
+ *
+ * Runs extension bootstrap functions in sequence.
+ * Bootstrap hooks execute AFTER database connection but BEFORE integration
+ * router creation. This is the right place for extensions to:
+ *
+ * - Load credentials from database into integration definitions
+ * - Register additional middleware or services
+ * - Perform one-time initialization
+ *
+ * @example
+ * await runExtensionBootstraps(extensions, { prisma, appDefinition });
+ */
+
+/**
+ * Runs all extension bootstrap functions in sequence.
+ *
+ * @param {Array<Object>} extensions - Normalized extensions (from extension-loader)
+ * @param {Object} context
+ * @param {Object} context.prisma - Prisma client instance
+ * @param {Object} context.appDefinition - Full app definition
+ * @throws {Error} If any bootstrap function fails (fails fast)
+ */
+async function runExtensionBootstraps(extensions, context = {}) {
+    if (!extensions || extensions.length === 0) return;
+
+    const { prisma, appDefinition } = context;
+
+    for (const ext of extensions) {
+        if (!ext.bootstrap) continue;
+
+        try {
+            await ext.bootstrap(prisma, appDefinition);
+        } catch (error) {
+            throw new Error(
+                `Extension "${ext.name}" bootstrap failed: ${error.message}`
+            );
+        }
+    }
+}
+
+module.exports = { runExtensionBootstraps };