@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.686.821f8a3.0

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

@@ -4,8 +4,41 @@
  * 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 {
-    constructor({ cryptor, schema }) {
+    /**
+     * @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 }) {
         if (!cryptor) {
             throw new Error('Cryptor instance required');
         }
@@ -15,6 +48,10 @@ class FieldEncryptionService {
 
         this.cryptor = cryptor;
         this.schema = schema;
+        this.failClosedOnDecryptError =
+            typeof failClosedOnDecryptError === 'function'
+                ? failClosedOnDecryptError
+                : () => isDeployedRuntime();
     }
 
     /**
@@ -97,12 +134,33 @@ class FieldEncryptionService {
         const decryptionPromises = fields.map(async (fieldPath) => {
             const value = this._getNestedValue(decrypted, fieldPath);
 
-            if (this._isEncrypted(value)) {
+            if (!this._isEncrypted(value)) {
+                return null;
+            }
+            try {
                 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);
@@ -152,7 +210,13 @@ class FieldEncryptionService {
         }
 
         const parts = value.split(':');
-        return parts.length >= 4;
+        return (
+            parts.length === 4 &&
+            BASE64_PART.test(parts[0]) &&
+            IV_PART.test(parts[1]) &&
+            CIPHERTEXT_PART.test(parts[2]) &&
+            BASE64_PART.test(parts[3])
+        );
     }
 
     _getNestedValue(obj, path) {
@@ -251,4 +315,4 @@ class FieldEncryptionService {
     }
 }
 
-module.exports = { FieldEncryptionService };
+module.exports = { FieldEncryptionService, FieldDecryptionError };

package/database/encryption/test-support/fake-ciphertext.js

@@ -0,0 +1,15 @@
+/**
+ * Test double for Cryptor output. Same shape as the real thing
+ * (`keyId:iv:ciphertext:encryptedKey`: base64, 16-byte hex, hex, base64) so
+ * FieldEncryptionService._isEncrypted accepts it, with the plaintext
+ * recoverable for the fake decrypt.
+ */
+const fakeCiphertext = (plain) =>
+    `a2V5SWQ=:${'0'.repeat(32)}:${Buffer.from(String(plain)).toString(
+        'hex'
+    )}:ZW5jS2V5`;
+
+const fakePlaintext = (ciphertext) =>
+    Buffer.from(String(ciphertext).split(':')[2], 'hex').toString();
+
+module.exports = { fakeCiphertext, fakePlaintext };

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

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

package/extensions/route-mounter.js

@@ -0,0 +1,103 @@
+/**
+ * Route Mounter
+ *
+ * Mounts extension-defined Express routers onto the main app.
+ * Each extension can declare routes with a base path and a handler factory.
+ *
+ * The handler factory receives (prisma, appDefinition) and returns an Express Router.
+ * Routes are protected by the admin auth middleware by default.
+ *
+ * @example
+ * mountExtensionRoutes(app, extensions, { prisma, appDefinition });
+ */
+
+const { validateAdminApiKey } = require('../handlers/middleware/admin-auth');
+
+/**
+ * Mounts all extension routes onto an Express app.
+ *
+ * @param {import('express').Express} app - Express app or router to mount on
+ * @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
+ * @param {Function} [context.authMiddleware] - Override admin auth middleware
+ */
+function mountExtensionRoutes(app, extensions, context = {}) {
+    if (!extensions || extensions.length === 0) return;
+
+    const { prisma, appDefinition, authMiddleware } = context;
+    const adminAuth = authMiddleware || validateAdminApiKey;
+
+    for (const ext of extensions) {
+        if (!ext.routes) continue;
+
+        const { path: basePath, handler } = ext.routes;
+
+        let router;
+        if (typeof handler === 'function') {
+            // Handler factory: (prisma, appDefinition) => Router
+            router = handler(prisma, appDefinition);
+        } else if (handler && handler.router) {
+            // Direct router object export pattern: { router }
+            router = handler.router;
+        } else if (handler && handler.default && typeof handler.default === 'function') {
+            // ES module default export
+            router = handler.default(prisma, appDefinition);
+        } else {
+            console.warn(
+                `Extension "${ext.name}": routes.handler is not a function or router object, skipping`
+            );
+            continue;
+        }
+
+        // Mount with admin auth middleware
+        app.use(basePath, adminAuth, router);
+    }
+}
+
+module.exports = { mountExtensionRoutes };
+
+/**
+ * Builds one router serving every app-level extension's routes
+ * (`appDefinition.coreExtensions[].routes`), each behind the admin API key.
+ *
+ * Lazy by design: the extensions, their route factories and the Prisma
+ * client are only touched on the first request, so requiring a handler
+ * module never connects anything.
+ *
+ * @param {Object} [params]
+ * @param {Object} [params.appDefinition] - raw app Definition; defaults to
+ *   loadAppDefinition().appDefinition on first request.
+ * @param {Object} [params.prisma] - defaults to core's Prisma client.
+ * @returns {import('express').Router}
+ */
+function createExtensionRoutesRouter({ appDefinition, prisma } = {}) {
+    const express = require('express');
+    const outer = express.Router();
+    let inner = null;
+
+    outer.use((req, res, next) => {
+        if (!inner) {
+            const definition =
+                appDefinition ||
+                require('../handlers/app-definition-loader').loadAppDefinition()
+                    .appDefinition;
+            const { loadExtensions } = require('./extension-loader');
+            const extensions = loadExtensions(definition);
+            const built = express.Router();
+            if (extensions.some((ext) => ext.routes)) {
+                mountExtensionRoutes(built, extensions, {
+                    prisma: prisma || require('../database/prisma').prisma,
+                    appDefinition: definition,
+                });
+            }
+            inner = built;
+        }
+        return inner(req, res, next);
+    });
+
+    return outer;
+}
+
+module.exports.createExtensionRoutesRouter = createExtensionRoutesRouter;