@friggframework/core 2.0.0--canary.680.6bacd26.0 → 2.0.0--canary.686.821f8a3.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/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

@@ -229,22 +229,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;
+    }
 
-        const backendPackagePath = findNearestBackendPackageJson();
-        if (!backendPackagePath) {
-            return; // No backend found, skip custom schema
+    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 };
+            }
+        }
+
+        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);
-        const appDefinition = backendModule?.Definition;
+    const backendModule = require(backendIndexPath);
+    return backendModule?.Definition || null;
+}
+
+function loadCustomEncryptionSchema() {
+    try {
+        const appDefinition = readAppDefinitionForEncryption();
 
         if (!appDefinition) {
             return; // No app definition found
@@ -264,6 +322,15 @@ 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) {
@@ -425,6 +492,7 @@ module.exports = {
     registerEncryptionOptOut,
     loadCustomEncryptionSchema,
     loadModuleEncryptionSchemas,
+    loadExtensionEncryptionSchemas,
     extractCredentialFieldsFromModules,
     validateCustomSchema,
     validateOptOut,

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 };

package/extensions/extension-loader.js

@@ -0,0 +1,187 @@
+/**
+ * Extension Loader
+ *
+ * Validates and normalizes the core extensions of the app definition
+ * (`appDefinition.coreExtensions`, an array). Core extensions add custom
+ * Prisma models, encryption schemas, admin routes and bootstrap logic to a
+ * Frigg app. The key is `coreExtensions`, not `extensions`: ADR-017 keeps
+ * `appDefinition.extensions` for its keyed object form.
+ *
+ * @example
+ * const extensions = loadExtensions(appDefinition);
+ * // extensions is a normalized array, safe to iterate
+ */
+
+const path = require('path');
+const {
+    coreExtensionRoutePathError,
+} = require('../management-api/route-registry');
+
+/**
+ * Validates a single extension definition.
+ * @param {Object} ext - Raw extension config from app definition
+ * @param {number} index - Position in the coreExtensions array (for error messages)
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+function validateExtension(ext, index) {
+    const prefix = `coreExtensions[${index}]`;
+    const errors = [];
+
+    if (!ext || typeof ext !== 'object') {
+        errors.push(`${prefix}: must be an object`);
+        return { valid: false, errors };
+    }
+
+    if (!ext.name || typeof ext.name !== 'string') {
+        errors.push(`${prefix}.name: required string`);
+    }
+
+    // schema is optional — path to a .prisma file
+    if (ext.schema !== undefined) {
+        if (typeof ext.schema !== 'string') {
+            errors.push(`${prefix}.schema: must be a string (path to .prisma file)`);
+        } else if (!ext.schema.endsWith('.prisma')) {
+            errors.push(`${prefix}.schema: must end with .prisma`);
+        }
+    }
+
+    // encryption is optional — object with model names → { fields: [...] }
+    if (ext.encryption !== undefined) {
+        if (!ext.encryption || typeof ext.encryption !== 'object') {
+            errors.push(`${prefix}.encryption: must be an object`);
+        } else {
+            for (const [model, config] of Object.entries(ext.encryption)) {
+                if (!config || !Array.isArray(config.fields)) {
+                    errors.push(
+                        `${prefix}.encryption.${model}: must have a "fields" array`
+                    );
+                }
+            }
+        }
+    }
+
+    // routes is optional — { path, handler }
+    if (ext.routes !== undefined) {
+        if (!ext.routes || typeof ext.routes !== 'object') {
+            errors.push(`${prefix}.routes: must be an object with { path, handler }`);
+        } else {
+            if (!ext.routes.path || typeof ext.routes.path !== 'string') {
+                errors.push(`${prefix}.routes.path: required string`);
+            } else {
+                const pathError = coreExtensionRoutePathError(ext.routes.path);
+                if (pathError) {
+                    errors.push(`${prefix}.routes.path: ${pathError}`);
+                }
+            }
+            if (!ext.routes.handler) {
+                errors.push(`${prefix}.routes.handler: required (function or module path)`);
+            }
+        }
+    }
+
+    // bootstrap is optional — function or module path
+    if (ext.bootstrap !== undefined) {
+        if (typeof ext.bootstrap !== 'function' && typeof ext.bootstrap !== 'string') {
+            errors.push(
+                `${prefix}.bootstrap: must be a function or a string (module path)`
+            );
+        }
+    }
+
+    return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Loads and validates extensions from the app definition.
+ *
+ * @param {Object} appDefinition - The full app definition
+ * @returns {Array<Object>} Normalized extensions array (empty if none)
+ * @throws {Error} If any extension fails validation
+ */
+function loadExtensions(appDefinition) {
+    if (!appDefinition) return [];
+
+    // The array this loader reads used to be `appDefinition.extensions`;
+    // that key now belongs to ADR-017's keyed object. An array there is the
+    // old spelling: stop at load rather than silently dropping the extensions.
+    if (Array.isArray(appDefinition.extensions)) {
+        throw new Error(
+            'appDefinition.extensions (array) was renamed to appDefinition.coreExtensions; ' +
+                'move the array to coreExtensions'
+        );
+    }
+
+    const raw = appDefinition.coreExtensions;
+    if (!raw) return [];
+
+    if (!Array.isArray(raw)) {
+        throw new Error('appDefinition.coreExtensions must be an array');
+    }
+
+    if (raw.length === 0) return [];
+
+    const allErrors = [];
+
+    const normalized = raw.map((ext, index) => {
+        const { valid, errors } = validateExtension(ext, index);
+        if (!valid) {
+            allErrors.push(...errors);
+            return null;
+        }
+
+        // Normalize bootstrap — resolve string paths to functions
+        let bootstrapFn = null;
+        if (typeof ext.bootstrap === 'function') {
+            bootstrapFn = ext.bootstrap;
+        } else if (typeof ext.bootstrap === 'string') {
+            bootstrapFn = require(ext.bootstrap);
+        }
+
+        // Normalize route handler — resolve string paths to functions
+        let routeHandler = null;
+        if (ext.routes) {
+            if (typeof ext.routes.handler === 'function') {
+                routeHandler = ext.routes.handler;
+            } else if (typeof ext.routes.handler === 'string') {
+                routeHandler = require(ext.routes.handler);
+            } else {
+                routeHandler = ext.routes.handler;
+            }
+        }
+
+        return {
+            name: ext.name,
+            schema: ext.schema || null,
+            encryption: ext.encryption || null,
+            routes: ext.routes
+                ? { path: ext.routes.path, handler: routeHandler }
+                : null,
+            bootstrap: bootstrapFn,
+        };
+    });
+
+    if (allErrors.length > 0) {
+        throw new Error(
+            `Invalid extension configuration:\n- ${allErrors.join('\n- ')}`
+        );
+    }
+
+    return normalized.filter(Boolean);
+}
+
+/**
+ * Get extension schema file paths from loaded extensions.
+ * @param {Array<Object>} extensions - Normalized extensions
+ * @returns {string[]} Array of absolute paths to .prisma schema files
+ */
+function getExtensionSchemaPaths(extensions) {
+    return extensions
+        .filter((ext) => ext.schema)
+        .map((ext) => ext.schema);
+}
+
+module.exports = {
+    loadExtensions,
+    validateExtension,
+    getExtensionSchemaPaths,
+};

package/extensions/index.js

@@ -0,0 +1,41 @@
+/**
+ * Frigg Extension System
+ *
+ * Extensions allow integration developers to extend Frigg Core with:
+ * - Custom Prisma models (schema composition)
+ * - Encrypted fields (encryption registry merge)
+ * - Admin API routes (route mounting)
+ * - Bootstrap lifecycle hooks (credential loading, etc.)
+ *
+ * @module @friggframework/core/extensions
+ */
+
+const { loadExtensions, validateExtension, getExtensionSchemaPaths } = require('./extension-loader');
+const { composeSchemas, extractModelBlocks, getSchemaFilePaths } = require('./schema-composer');
+const {
+    mountExtensionRoutes,
+    createExtensionRoutesRouter,
+} = require('./route-mounter');
+const { runExtensionBootstraps } = require('./bootstrap-runner');
+const { initializeApp, resetInitialization } = require('./initialize-app');
+
+module.exports = {
+    // Extension loading & validation
+    loadExtensions,
+    validateExtension,
+    getExtensionSchemaPaths,
+
+    // Schema composition
+    composeSchemas,
+    extractModelBlocks,
+    getSchemaFilePaths,
+
+    // Route mounting
+    mountExtensionRoutes,
+    createExtensionRoutesRouter,
+
+    // Bootstrap lifecycle
+    runExtensionBootstraps,
+    initializeApp,
+    resetInitialization,
+};