@friggframework/core 2.0.0--canary.686.df38e8e.0 → 2.0.0--canary.710.9045bbc.0

package/database/encryption/encryption-config.js

@@ -1,219 +0,0 @@
-/**
- * Field-level encryption configuration: decides whether sensitive fields are
- * encrypted, and with which key, from the process environment.
- *
- * The rule fails closed:
- *
- * - **Deployed** (running in AWS Lambda, and not under
- *   serverless-offline, `serverless invoke local` or Jest): the stage name is
- *   ignored. A configured key (KMS_KEY_ARN, or AES_KEY_ID with AES_KEY) turns
- *   encryption on. With no key, the configuration is an error and the Prisma
- *   client refuses to start, unless FRIGG_ENCRYPTION_DISABLED=true opts out
- *   explicitly.
- * - **Local** (`frigg start`, tests, scripts on a laptop): the stages dev,
- *   test and local skip encryption. Any other stage encrypts when a key is
- *   configured and stays plaintext, with a warning, when none is.
- *
- * Every module that encrypts or reports on encryption reads this one rule.
- */
-
-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';
-
-class EncryptionConfigurationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'EncryptionConfigurationError';
-    }
-}
-
-function isSet(value) {
-    return typeof value === 'string' && value.trim() !== '';
-}
-
-function isTrue(value) {
-    if (typeof value !== 'string') return false;
-    const normalized = value.trim().toLowerCase();
-    return normalized === 'true' || normalized === '1';
-}
-
-/**
- * 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) {
-    return isDeployedProviderRuntime(env);
-}
-
-function missingKeyMessage(stage) {
-    return (
-        `[Frigg] No field-level encryption key is configured for stage "${stage}". ` +
-        'A deployed Frigg app will not write credentials and other sensitive fields in plaintext. ' +
-        "Fix: set encryption: { fieldLevelEncryptionMethod: 'kms' } in the app definition and redeploy " +
-        '(Frigg creates or discovers a KMS key and sets KMS_KEY_ARN), ' +
-        'or provide AES_KEY_ID and AES_KEY (32 characters) in the Lambda environment. ' +
-        `To run this stage without encryption on purpose, set ${OPT_OUT_VAR}=true ` +
-        "(or encryption: { fieldLevelEncryptionMethod: 'none' } in the app definition)."
-    );
-}
-
-function incompleteAesMessage(stage) {
-    return (
-        `[Frigg] AES_KEY_ID is set but AES_KEY is not (stage "${stage}"). ` +
-        'Provide AES_KEY (32 characters) alongside AES_KEY_ID, ' +
-        "or use KMS with encryption: { fieldLevelEncryptionMethod: 'kms' }."
-    );
-}
-
-/**
- * Resolves the encryption configuration without side effects.
- *
- * @param {Object} [env=process.env]
- * @returns {{
- *   enabled: boolean,
- *   method: 'kms'|'aes'|undefined,
- *   mode: 'kms'|'aes'|'none',
- *   runtime: 'deployed'|'local',
- *   stage: string,
- *   bypassed: boolean,
- *   optedOut: boolean,
- *   optOutIgnored: boolean,
- *   hasKMS: boolean,
- *   hasAES: boolean,
- *   error: string|null,
- * }} `error` is set when a deployed runtime has no usable key.
- */
-function resolveEncryptionConfig(env = process.env) {
-    const stage = env.STAGE || env.NODE_ENV || 'development';
-    const runtime = isDeployedRuntime(env) ? 'deployed' : 'local';
-    const hasKMS = isSet(env.KMS_KEY_ARN);
-    const hasAES = isSet(env.AES_KEY_ID);
-    const optOutRequested = isTrue(env[OPT_OUT_VAR]);
-
-    const base = {
-        enabled: false,
-        method: undefined,
-        mode: 'none',
-        runtime,
-        stage,
-        bypassed: false,
-        optedOut: false,
-        optOutIgnored: false,
-        hasKMS,
-        hasAES,
-        error: null,
-    };
-
-    if (runtime === 'local') {
-        if (LOCAL_BYPASS_STAGES.includes(String(stage).toLowerCase())) {
-            return { ...base, bypassed: true };
-        }
-        if (hasKMS || hasAES) {
-            const method = hasKMS ? 'kms' : 'aes';
-            return { ...base, enabled: true, method, mode: method };
-        }
-        return base;
-    }
-
-    const hasCompleteAES = hasAES && isSet(env.AES_KEY);
-    if (hasKMS || hasCompleteAES) {
-        const method = hasKMS ? 'kms' : 'aes';
-        return {
-            ...base,
-            enabled: true,
-            method,
-            mode: method,
-            optOutIgnored: optOutRequested,
-        };
-    }
-
-    if (optOutRequested) {
-        return { ...base, optedOut: true };
-    }
-
-    return {
-        ...base,
-        error: hasAES ? incompleteAesMessage(stage) : missingKeyMessage(stage),
-    };
-}
-
-const warned = new Set();
-
-function warnOnce(key, message) {
-    if (warned.has(key)) return;
-    warned.add(key);
-    logger.warn(message);
-}
-
-/**
- * Resolves the encryption configuration for use: throws when a deployed
- * runtime has no usable key, and warns once per process (once per Lambda
- * cold start) when encryption is explicitly disabled.
- *
- * @param {Object} [env=process.env]
- * @returns {ReturnType<typeof resolveEncryptionConfig>}
- * @throws {EncryptionConfigurationError}
- */
-function getEncryptionConfig(env = process.env) {
-    const config = resolveEncryptionConfig(env);
-
-    if (config.error) {
-        throw new EncryptionConfigurationError(config.error);
-    }
-
-    if (config.optedOut) {
-        warnOnce(
-            'opted-out',
-            `[Frigg] ${OPT_OUT_VAR}=true: field-level encryption is OFF for stage "${config.stage}". ` +
-                'Credentials and other sensitive fields are stored in PLAINTEXT. ' +
-                `Remove ${OPT_OUT_VAR} and configure a key (fieldLevelEncryptionMethod: 'kms') to encrypt them.`
-        );
-    }
-
-    if (config.optOutIgnored) {
-        warnOnce(
-            'opt-out-ignored',
-            `[Frigg] ${OPT_OUT_VAR}=true is ignored because an encryption key is configured; ` +
-                `fields are encrypted with ${config.method.toUpperCase()}. ` +
-                'Turning encryption off while a key is present would leave encrypted data unreadable.'
-        );
-    }
-
-    if (config.runtime === 'local' && !config.enabled && !config.bypassed) {
-        warnOnce(
-            'local-no-keys',
-            `No encryption keys configured (KMS_KEY_ARN or AES_KEY_ID) for local stage "${config.stage}". ` +
-                'Field-level encryption disabled for this local run. ' +
-                'A deployed stage without a key refuses to start.'
-        );
-    }
-
-    return config;
-}
-
-/** Test helper: let the once-per-process warnings fire again. */
-function resetEncryptionConfigWarnings() {
-    warned.clear();
-}
-
-module.exports = {
-    EncryptionConfigurationError,
-    LOCAL_BYPASS_STAGES,
-    OPT_OUT_VAR,
-    getEncryptionConfig,
-    isDeployedRuntime,
-    resetEncryptionConfigWarnings,
-    resolveEncryptionConfig,
-};

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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,18 +0,0 @@
-/**
- * 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/unique-violation.js

@@ -1,25 +0,0 @@
-/** 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

@@ -1,43 +0,0 @@
-/**
- * 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

@@ -1,187 +0,0 @@
-/**
- * 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

@@ -1,41 +0,0 @@
-/**
- * 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

@@ -1,123 +0,0 @@
-/**
- * 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,
-};