@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/database/prisma.js

@@ -4,6 +4,7 @@ const {
 const { loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
 const { logger } = require('./encryption/logger');
 const { Cryptor } = require('../encrypt/Cryptor');
+const { getEncryptionConfig } = require('./encryption/encryption-config');
 const config = require('./config');
 
 /**
@@ -32,33 +33,6 @@ function ensureMongoDbUrl() {
     );
 }
 
-function getEncryptionConfig() {
-    const STAGE = process.env.STAGE || process.env.NODE_ENV || 'development';
-    const shouldBypassEncryption = ['dev', 'test', 'local'].includes(STAGE);
-
-    if (shouldBypassEncryption) {
-        return { enabled: false };
-    }
-
-    const hasKMS =
-        process.env.KMS_KEY_ARN && process.env.KMS_KEY_ARN.trim() !== '';
-    const hasAES =
-        process.env.AES_KEY_ID && process.env.AES_KEY_ID.trim() !== '';
-
-    if (!hasKMS && !hasAES) {
-        logger.warn(
-            'No encryption keys configured (KMS_KEY_ARN or AES_KEY_ID). ' +
-            'Field-level encryption disabled. Set STAGE=production and configure keys to enable.'
-        );
-        return { enabled: false };
-    }
-
-    return {
-        enabled: true,
-        method: hasKMS ? 'kms' : 'aes',
-    };
-}
-
 const prismaClientSingleton = () => {
     let PrismaClient;
 
@@ -67,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
             }
@@ -103,9 +79,13 @@ const prismaClientSingleton = () => {
         errorFormat: 'pretty',
     });
 
+    // Throws when a deployed runtime has no encryption key: the app must not
+    // start and write sensitive fields in plaintext.
     const encryptionConfig = getEncryptionConfig();
 
     if (encryptionConfig.enabled) {
+        // Fail closed: if the extension cannot be installed, do not hand out
+        // a client that would write plaintext.
         try {
             // Load custom encryption schema from appDefinition before creating extension
             loadCustomEncryptionSchema();
@@ -120,17 +100,14 @@ const prismaClientSingleton = () => {
                     enabled: true,
                 })
             );
-
-            logger.info(
-                `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
-            );
         } catch (error) {
-            logger.error(
-                'Failed to initialize encryption extension:',
-                error
-            );
-            logger.warn('Continuing without encryption...');
+            logger.error('Failed to initialize encryption extension:', error);
+            throw error;
         }
+
+        logger.info(
+            `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
+        );
     } else {
         logger.info('Field-level encryption disabled');
     }

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/database/use-cases/check-encryption-health-use-case.js

@@ -1,3 +1,12 @@
+const {
+    resolveEncryptionConfig,
+    OPT_OUT_VAR,
+} = require('../encryption/encryption-config');
+
+/**
+ * Reports whether field-level encryption is on and working, using the same
+ * rule the Prisma client applies at startup (encryption/encryption-config.js).
+ */
 class CheckEncryptionHealthUseCase {
     constructor({ testEncryptionUseCase }) {
         this.testEncryptionUseCase = testEncryptionUseCase;
@@ -5,78 +14,60 @@ class CheckEncryptionHealthUseCase {
 
     async execute() {
         const config = this._getEncryptionConfiguration();
+        const summary = {
+            mode: config.mode,
+            bypassed: config.bypassed,
+            optedOut: config.optedOut,
+            runtime: config.runtime,
+            stage: config.stage,
+            debug: {
+                hasKMS: config.hasKMS,
+                hasAES: config.hasAES,
+            },
+        };
 
-        if (config.isBypassed || config.mode === 'none') {
-            const testResult = config.isBypassed
-                ? 'Encryption bypassed for this stage'
-                : 'No encryption keys configured';
+        if (config.error) {
+            return {
+                status: 'unhealthy',
+                ...summary,
+                testResult: config.error,
+                encryptionWorks: false,
+            };
+        }
 
+        if (!config.enabled) {
             return {
                 status: 'disabled',
-                mode: config.mode,
-                bypassed: config.isBypassed,
-                stage: config.stage,
-                testResult,
+                ...summary,
+                testResult: this._disabledReason(config),
                 encryptionWorks: false,
-                debug: {
-                    hasKMS: config.hasKMS,
-                    hasAES: config.hasAES,
-                },
             };
         }
 
         try {
             const testResults = await this.testEncryptionUseCase.execute();
-
-            return {
-                ...testResults,
-                mode: config.mode,
-                bypassed: config.isBypassed,
-                stage: config.stage,
-                debug: {
-                    hasKMS: config.hasKMS,
-                    hasAES: config.hasAES,
-                },
-            };
+            return { ...testResults, ...summary };
         } catch (error) {
             return {
                 status: 'unhealthy',
-                mode: config.mode,
-                bypassed: config.isBypassed,
-                stage: config.stage,
+                ...summary,
                 testResult: `Encryption test failed: ${error.message}`,
                 encryptionWorks: false,
-                debug: {
-                    hasKMS: config.hasKMS,
-                    hasAES: config.hasAES,
-                },
             };
         }
     }
 
-    _getEncryptionConfiguration() {
-        const { STAGE, BYPASS_ENCRYPTION_STAGE, KMS_KEY_ARN, AES_KEY_ID } =
-            process.env;
-
-        const defaultBypassStages = ['dev', 'test', 'local'];
-        const useEnv = BYPASS_ENCRYPTION_STAGE !== undefined;
-        const bypassStages = useEnv
-            ? BYPASS_ENCRYPTION_STAGE.split(',').map((s) => s.trim())
-            : defaultBypassStages;
-
-        const isBypassed = bypassStages.includes(STAGE);
-        const hasAES = AES_KEY_ID && AES_KEY_ID.trim() !== '';
-        const hasKMS = KMS_KEY_ARN && KMS_KEY_ARN.trim() !== '';
-        // Prefer KMS over AES when both are configured (KMS is more secure)
-        const mode = hasKMS ? 'kms' : hasAES ? 'aes' : 'none';
+    _disabledReason(config) {
+        if (config.bypassed) return 'Encryption bypassed for this stage';
+        if (config.optedOut) {
+            return `Encryption explicitly disabled (${OPT_OUT_VAR}=true); sensitive fields are stored in plaintext`;
+        }
+        return 'No encryption keys configured';
+    }
 
-        return {
-            stage: STAGE || null,
-            isBypassed,
-            hasAES,
-            hasKMS,
-            mode,
-        };
+    _getEncryptionConfiguration() {
+        const config = resolveEncryptionConfig(process.env);
+        return { ...config, stage: process.env.STAGE || null };
     }
 }
 

package/errors/index.js

@@ -6,9 +6,6 @@ const {
     ParameterTypeError,
 } = require('./validation-errors');
 const { ClientSafeError } = require('./client-safe-error');
-const {
-    MappingAlreadyExistsError,
-} = require('./mapping-already-exists-error');
 
 module.exports = {
     BaseError,
@@ -17,5 +14,4 @@ module.exports = {
     RequiredPropertyError,
     ParameterTypeError,
     ClientSafeError,
-    MappingAlreadyExistsError,
 };

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

package/extensions/initialize-app.js

@@ -0,0 +1,123 @@
+/**
+ * Application Initialization with Extension Lifecycle
+ *
+ * Provides an async initialization function that runs extension bootstraps
+ * after database connection but before router creation. This is the integration
+ * point for providers (Lambda, Netlify) to hook into the extension lifecycle.
+ *
+ * Call `initializeApp()` during the async startup phase of your handler/function.
+ * It is safe to call multiple times — subsequent calls are no-ops.
+ *
+ * @example
+ * const { initializeApp } = require('@friggframework/core/extensions/initialize-app');
+ *
+ * // In a Lambda handler or Netlify function:
+ * await initializeApp();
+ * // Now extensions are bootstrapped and router can be created
+ */
+
+const { loadExtensions } = require('./extension-loader');
+const { runExtensionBootstraps } = require('./bootstrap-runner');
+
+let _initialized = false;
+let _initPromise = null;
+
+/**
+ * Initializes extensions by running bootstrap hooks.
+ *
+ * This function:
+ * 1. Loads the app definition
+ * 2. Loads and validates extensions
+ * 3. Runs extension bootstrap hooks in sequence
+ *
+ * Bootstrap hooks receive (prisma, appDefinition) and can:
+ * - Load credentials from database into integration Definition.env
+ * - Register services or middleware
+ * - Perform any one-time async initialization
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.appDefinition] - Override app definition (skips loadAppDefinition)
+ * @param {Object} [options.prisma] - Override Prisma client instance
+ * @param {boolean} [options.force=false] - Force re-initialization
+ * @returns {Promise<{extensions: Array}>} The loaded extensions
+ */
+async function initializeApp(options = {}) {
+    const { force = false } = options;
+
+    // Return cached promise if already initializing (prevent race conditions)
+    if (_initPromise && !force) {
+        return _initPromise;
+    }
+
+    if (_initialized && !force) {
+        return { extensions: [] };
+    }
+
+    _initPromise = _doInitialize(options);
+
+    try {
+        const result = await _initPromise;
+        _initialized = true;
+        return result;
+    } catch (error) {
+        _initPromise = null;
+        throw error;
+    }
+}
+
+async function _doInitialize(options = {}) {
+    let { appDefinition, prisma } = options;
+
+    // Load app definition if not provided
+    if (!appDefinition) {
+        try {
+            const { loadAppDefinition } = require('../handlers/app-definition-loader');
+            const loaded = loadAppDefinition();
+            appDefinition = loaded.appDefinition;
+        } catch {
+            // No app definition available — skip extension bootstrap
+            return { extensions: [] };
+        }
+    }
+
+    if (!appDefinition) {
+        return { extensions: [] };
+    }
+
+    // Load extensions
+    const extensions = loadExtensions(appDefinition);
+
+    if (extensions.length === 0) {
+        return { extensions };
+    }
+
+    // Get Prisma client if not provided
+    if (!prisma) {
+        try {
+            const db = require('../database/prisma');
+            prisma = db.prisma;
+        } catch {
+            // Prisma not available — skip bootstrap
+            console.warn('Prisma client not available, skipping extension bootstraps');
+            return { extensions };
+        }
+    }
+
+    // Run bootstrap hooks
+    await runExtensionBootstraps(extensions, { prisma, appDefinition });
+
+    return { extensions };
+}
+
+/**
+ * Reset initialization state (for testing).
+ */
+function resetInitialization() {
+    _initialized = false;
+    _initPromise = null;
+}
+
+module.exports = {
+    initializeApp,
+    resetInitialization,
+};