@friggframework/core 2.0.0-next.12 → 2.0.0-next.121

package/database/config.js

@@ -0,0 +1,147 @@
+/**
+ * Database Configuration
+ * Manages configuration for Prisma ORM operations
+ */
+
+/**
+ * Determines database type from environment or app definition
+ * 
+ * Detection order:
+ * 1. DB_TYPE environment variable (set for migration handlers)
+ * 2. App definition (backend/index.js Definition.database configuration)
+ *
+ * @returns {'mongodb'|'postgresql'|'documentdb'} Database type
+ * @throws {Error} If database type cannot be determined or app definition missing
+ */
+function getDatabaseType() {
+    // First, check DB_TYPE environment variable (migration handlers set this)
+    if (process.env.DB_TYPE) {
+        return process.env.DB_TYPE;
+    }
+
+    // Fallback: Load app definition
+    try {
+        const path = require('node:path');
+        const fs = require('node:fs');
+        const { findNearestBackendPackageJson } = require('../utils');
+
+        let backendIndexPath;
+        let database;
+        const backendPackagePath = findNearestBackendPackageJson();
+
+        if (!backendPackagePath) {
+            throw new Error(
+                '[Frigg] Cannot find backend package.json. ' +
+                'Ensure backend/package.json exists in your project.'
+            );
+        }
+
+        const backendDir = path.dirname(backendPackagePath);
+        backendIndexPath = path.join(backendDir, 'index.js');
+
+        if (!fs.existsSync(backendIndexPath)) {
+            throw new Error(
+                `[Frigg] Backend index.js not found at ${backendIndexPath}. ` +
+                'Ensure backend/index.js exists with a Definition export.'
+            );
+        }
+
+        let backendModule;
+        try {
+            backendModule = require(backendIndexPath);
+        } catch (requireError) {
+            // Extract the actual file with the error from the stack trace
+            // Skip internal Node.js files (node:internal/*) and find first user file
+            let errorFile = 'unknown file';
+            const stackLines = requireError.stack?.split('\n') || [];
+
+            for (const line of stackLines) {
+                // Match file paths in stack trace, excluding node:internal
+                const match = line.match(/\(([^)]+\.js):\d+:\d+\)/) || line.match(/at ([^(]+\.js):\d+:\d+/);
+                if (match && match[1] && !match[1].includes('node:internal')) {
+                    errorFile = match[1];
+                    break;
+                }
+            }
+
+            // Provide better error context for syntax/runtime errors
+            throw new Error(
+                `[Frigg] Failed to load app definition from ${backendIndexPath}\n` +
+                `Error: ${requireError.message}\n` +
+                `File with error: ${errorFile}\n` +
+                `\nFull stack trace:\n${requireError.stack}\n\n` +
+                'This error occurred while loading your app definition or its dependencies. ' +
+                'Check the file listed above for syntax errors (trailing commas, missing brackets, etc.)'
+            );
+        }
+
+        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'
+        );
+    } catch (error) {
+        // Re-throw with context if it's our error
+        if (error.message.includes('[Frigg]')) {
+            throw error;
+        }
+        // Wrap unexpected errors
+        throw new Error(
+            `[Frigg] Failed to determine database type: ${error.message}`
+        );
+    }
+}
+
+/**
+ * Cached database type (lazy evaluation)
+ * @type {'mongodb'|'postgresql'|'documentdb'|null}
+ */
+let cachedDbType = null;
+
+/**
+ * Enable Prisma debug logging
+ * Set PRISMA_LOG_LEVEL to comma-separated list: query,info,warn,error
+ * @type {string}
+ */
+const PRISMA_LOG_LEVEL = process.env.PRISMA_LOG_LEVEL || 'error,warn';
+
+module.exports = {
+    getDatabaseType, // Export for testing and direct use
+    PRISMA_LOG_LEVEL,
+};
+
+/**
+ * Lazy-evaluated database type determined from app definition
+ * Only evaluates when accessed, preventing module load failures in test environments
+ * @type {'mongodb'|'postgresql'|'documentdb'}
+ */
+Object.defineProperty(module.exports, 'DB_TYPE', {
+    get() {
+        if (cachedDbType === null) {
+            cachedDbType = getDatabaseType();
+        }
+        return cachedDbType;
+    },
+    enumerable: true,
+    configurable: true
+});

package/database/documentdb-encryption-service.js

@@ -0,0 +1,334 @@
+const { Cryptor } = require('../encrypt/Cryptor');
+const {
+    getEncryptedFields,
+    getFieldsToEncryptOnWrite,
+    loadCustomEncryptionSchema,
+} = require('./encryption/encryption-schema-registry');
+
+/**
+ * Encryption service specifically for DocumentDB repositories
+ * that use $runCommandRaw and bypass Prisma Client Extensions.
+ *
+ * Provides document-level encryption/decryption, handling nested fields
+ * according to the encryption schema registry.
+ *
+ * @class DocumentDBEncryptionService
+ * @example
+ * const service = new DocumentDBEncryptionService();
+ *
+ * // Encrypt before write
+ * const encrypted = await service.encryptFields('Credential', document);
+ * await insertOne(prisma, 'Credential', encrypted);
+ *
+ * // Decrypt after read
+ * const doc = await findOne(prisma, 'Credential', filter);
+ * const decrypted = await service.decryptFields('Credential', doc);
+ */
+class DocumentDBEncryptionService {
+    /**
+     * @param {Object} options - Configuration options
+     * @param {Cryptor} [options.cryptor] - Optional Cryptor instance for dependency injection (useful for testing)
+     */
+    constructor({ cryptor = null } = {}) {
+        if (cryptor) {
+            // Dependency injection - use provided Cryptor (for testing)
+            this.cryptor = cryptor;
+            this.enabled = true;
+        } else {
+            // Default behavior - create Cryptor from environment
+            this._initializeCryptor();
+        }
+    }
+
+    /**
+     * Initialize Cryptor with environment-based configuration.
+     * Matches the logic from @friggframework/core/database/prisma.js
+     *
+     * Encryption is bypassed in dev/test/local stages.
+     * Production uses AWS KMS (if available) or AES encryption.
+     *
+     * @private
+     */
+    _initializeCryptor() {
+        // Load custom encryption schema from app definition BEFORE checking configuration
+        // This ensures custom fields (like User.username) are registered before any encryption operations
+        loadCustomEncryptionSchema();
+
+        // Match logic from packages/core/database/prisma.js
+        const stage = process.env.STAGE || process.env.NODE_ENV || 'development';
+        const bypassEncryption = ['dev', 'test', 'local'].includes(stage.toLowerCase());
+
+        if (bypassEncryption) {
+            this.cryptor = null;
+            this.enabled = false;
+            return;
+        }
+
+        // Determine encryption method (ensure boolean values)
+        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) {
+            console.warn('[DocumentDBEncryptionService] No encryption keys configured. Encryption disabled.');
+            this.cryptor = null;
+            this.enabled = false;
+            return;
+        }
+
+        // KMS takes precedence over AES
+        const shouldUseAws = hasKMS;
+        this.cryptor = new Cryptor({ shouldUseAws });
+        this.enabled = true;
+    }
+
+    /**
+     * Encrypt sensitive fields in a document before storing to DocumentDB.
+     *
+     * Reads field paths from encryption-schema-registry.js and encrypts
+     * only the fields defined for the given model.
+     *
+     * @param {string} modelName - Model name from schema registry (e.g., 'User', 'Credential')
+     * @param {Object} document - Document to encrypt
+     * @returns {Promise<Object>} - New document with encrypted fields (original unchanged)
+     *
+     * @example
+     * const plainDoc = {
+     *   userId: '123',
+     *   data: { access_token: 'plain_secret' }
+     * };
+     * const encrypted = await service.encryptFields('Credential', plainDoc);
+     * // encrypted.data.access_token = "keyId:iv:cipher:encKey"
+     */
+    async encryptFields(modelName, document) {
+        // Bypass if encryption disabled
+        if (!this.enabled || !this.cryptor) {
+            return document;
+        }
+
+        // Validate input
+        if (!document || typeof document !== 'object') {
+            return document;
+        }
+
+        // Get encrypted fields from registry
+        const encryptedFieldsConfig = getFieldsToEncryptOnWrite(modelName);
+        if (!encryptedFieldsConfig || encryptedFieldsConfig.length === 0) {
+            return document;
+        }
+
+        // Deep clone to prevent mutation (preserves Date, RegExp, Buffer)
+        const result = structuredClone(document);
+
+        // Encrypt each field path
+        for (const fieldPath of encryptedFieldsConfig) {
+            await this._encryptFieldPath(result, fieldPath, modelName);
+        }
+
+        return result;
+    }
+
+    /**
+     * Decrypt sensitive fields in a document after reading from DocumentDB.
+     *
+     * Reads field paths from encryption-schema-registry.js and decrypts
+     * only the fields defined for the given model.
+     *
+     * @param {string} modelName - Model name from schema registry
+     * @param {Object} document - Document to decrypt
+     * @returns {Promise<Object>} - New document with decrypted fields (original unchanged)
+     *
+     * @example
+     * const encryptedDoc = {
+     *   userId: '123',
+     *   data: { access_token: 'keyId:iv:cipher:encKey' }
+     * };
+     * const decrypted = await service.decryptFields('Credential', encryptedDoc);
+     * // decrypted.data.access_token = "plain_secret"
+     */
+    async decryptFields(modelName, document) {
+        // Bypass if encryption disabled
+        if (!this.enabled || !this.cryptor) {
+            return document;
+        }
+
+        // Validate input
+        if (!document || typeof document !== 'object') {
+            return document;
+        }
+
+        // Get encrypted fields from registry
+        const encryptedFieldsConfig = getEncryptedFields(modelName);
+        if (!encryptedFieldsConfig || encryptedFieldsConfig.length === 0) {
+            return document;
+        }
+
+        // Deep clone to prevent mutation (preserves Date, RegExp, Buffer)
+        const result = structuredClone(document);
+
+        // Decrypt each field path
+        for (const fieldPath of encryptedFieldsConfig) {
+            await this._decryptFieldPath(result, fieldPath, modelName);
+        }
+
+        return result;
+    }
+
+    /**
+     * Encrypt a specific field path in a document (handles nested fields).
+     *
+     * @private
+     * @param {Object} document - Document to modify (mutated in place)
+     * @param {string} fieldPath - Field path from schema registry (e.g., 'data.access_token')
+     * @param {string} modelName - For error logging context
+     */
+    async _encryptFieldPath(document, fieldPath, modelName) {
+        // Parse field path
+        const parts = fieldPath.split('.');
+
+        // Navigate to parent object
+        let current = document;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (!current[parts[i]]) {
+                // Path doesn't exist, nothing to encrypt
+                return;
+            }
+            current = current[parts[i]];
+        }
+
+        // Get field name and value
+        const fieldName = parts[parts.length - 1];
+        const value = current[fieldName];
+
+        // Skip if already encrypted or empty
+        if (!value || this._isEncryptedValue(value)) {
+            return;
+        }
+
+        try {
+            // Convert to string if needed
+            const stringValue = typeof value === 'string'
+                ? value
+                : JSON.stringify(value);
+
+            // Encrypt using Cryptor
+            current[fieldName] = await this.cryptor.encrypt(stringValue);
+        } catch (error) {
+            console.error(`[DocumentDBEncryptionService] Failed to encrypt ${modelName}.${fieldPath}:`, error.message);
+            throw error;
+        }
+    }
+
+    /**
+     * Decrypt a specific field path in a document (handles nested fields).
+     *
+     * @private
+     * @param {Object} document - Document to modify (mutated in place)
+     * @param {string} fieldPath - Field path from schema registry
+     * @param {string} modelName - For error logging context
+     */
+    async _decryptFieldPath(document, fieldPath, modelName) {
+        // Parse field path
+        const parts = fieldPath.split('.');
+
+        // Navigate to parent object
+        let current = document;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (!current[parts[i]]) {
+                // Path doesn't exist, nothing to decrypt
+                return;
+            }
+            current = current[parts[i]];
+        }
+
+        // Get field name and encrypted value
+        const fieldName = parts[parts.length - 1];
+        const encryptedValue = current[fieldName];
+
+        // Skip if not encrypted format
+        if (!encryptedValue || !this._isEncryptedValue(encryptedValue)) {
+            return;
+        }
+
+        try {
+            // Decrypt using Cryptor
+            const decryptedString = await this.cryptor.decrypt(encryptedValue);
+
+            // Try to parse as JSON (for objects/arrays)
+            try {
+                current[fieldName] = JSON.parse(decryptedString);
+            } catch {
+                // Not JSON, return as string
+                current[fieldName] = decryptedString;
+            }
+        } catch (error) {
+            const errorContext = {
+                modelName,
+                fieldPath,
+                encryptedValuePrefix: encryptedValue.substring(0, 20),
+                errorMessage: error.message
+            };
+
+            console.error(
+                `[DocumentDBEncryptionService] Failed to decrypt ${modelName}.${fieldPath}:`,
+                JSON.stringify(errorContext)
+            );
+
+            // Throw error to fail fast - don't silently corrupt data
+            throw new Error(`Decryption failed for ${modelName}.${fieldPath}: ${error.message}`);
+        }
+    }
+
+    /**
+     * Check if a value is in encrypted format.
+     *
+     * Encrypted format: "keyId:iv:cipher:encKey" (envelope encryption)
+     * All parts are base64-encoded strings.
+     *
+     * @private
+     * @param {any} value - Value to check
+     * @returns {boolean} - True if value is encrypted
+     *
+     * @example
+     * _isEncryptedValue("plain_text")  // false
+     * _isEncryptedValue("YWVzLWtleS0x:TXlJVkhlcmU=:QWN0dWFsQ2lwaGVy:RW5jcnlwdGVk")  // true
+     * _isEncryptedValue(null)  // false
+     * _isEncryptedValue({})  // false
+     */
+    _isEncryptedValue(value) {
+        // Must be string
+        if (typeof value !== 'string') {
+            return false;
+        }
+
+        // Must have exactly 4 colon-separated parts
+        const parts = value.split(':');
+        if (parts.length !== 4) {
+            return false;
+        }
+
+        // Enhanced validation: check for base64 pattern
+        // This prevents false positives on URLs, connection strings, etc.
+        const base64Pattern = /^[A-Za-z0-9+/=]+$/;
+
+        // All parts should be base64-encoded
+        if (!parts.every(part => base64Pattern.test(part))) {
+            return false;
+        }
+
+        // Encrypted values should be sufficiently long to be valid
+        // Real encrypted values from Cryptor are always >50 chars due to envelope encryption format:
+        // - keyId (base64): ~12 chars minimum
+        // - iv (base64): ~24 chars for 16-byte IV
+        // - ciphertext (base64): varies, minimum ~16 chars for small values
+        // - encryptedKey (base64): ~44 chars for 32-byte data key
+        // Total minimum: ~96 chars, so 50 is a safe lower bound
+        // This prevents false positives on non-encrypted strings that happen to have 4 colons
+        if (value.length < 50) {
+            return false;
+        }
+
+        return true;
+    }
+}
+
+module.exports = { DocumentDBEncryptionService };

package/database/documentdb-utils.js

@@ -0,0 +1,196 @@
+const { ObjectId } = require('bson');
+
+function toObjectId(value) {
+    if (value === null || value === undefined || value === '') return undefined;
+    if (value instanceof ObjectId) return value;
+    if (typeof value === 'object' && value.$oid) return new ObjectId(value.$oid);
+    if (typeof value === 'string') return ObjectId.isValid(value) ? new ObjectId(value) : undefined;
+    return undefined;
+}
+
+function toObjectIdArray(values) {
+    if (!Array.isArray(values)) return [];
+    return values.map(toObjectId).filter(Boolean);
+}
+
+function fromObjectId(value) {
+    if (value instanceof ObjectId) return value.toHexString();
+    if (typeof value === 'object' && value !== null && value.$oid) return value.$oid;
+    if (typeof value === 'string') return value;
+    return value === undefined || value === null ? value : String(value);
+}
+
+async function findMany(client, collection, filter = {}, options = {}) {
+    const command = { find: collection, filter };
+    if (options.projection) command.projection = options.projection;
+    if (options.sort) command.sort = options.sort;
+    if (options.limit) command.limit = options.limit;
+    const result = await client.$runCommandRaw(command);
+    return result?.cursor?.firstBatch || [];
+}
+
+async function findOne(client, collection, filter = {}, options = {}) {
+    const docs = await findMany(client, collection, filter, { ...options, limit: 1 });
+    return docs[0] || null;
+}
+
+async function insertOne(client, collection, document) {
+    // Generate ObjectId if not present (MongoDB raw insert doesn't return insertedIds)
+    const _id = document._id || new ObjectId();
+    const docWithId = { ...document, _id };
+
+    const result = await client.$runCommandRaw({
+        insert: collection,
+        documents: [docWithId],
+    });
+
+    // Validate insert succeeded
+    if (result.ok !== 1) {
+        throw new Error(
+            `Insert command failed for collection '${collection}': ${JSON.stringify(result)}`
+        );
+    }
+
+    // Check for write errors (duplicate keys, validation errors, etc.)
+    if (result.writeErrors && result.writeErrors.length > 0) {
+        const error = result.writeErrors[0];
+        const errorMsg = `Insert failed in '${collection}': ${error.errmsg} (code: ${error.code})`;
+
+        // Provide helpful context for common errors
+        if (error.code === 11000) {
+            throw Object.assign(
+                new Error(`${errorMsg} - Duplicate key violation`),
+                { code: 11000 }
+            );
+        }
+        throw new Error(errorMsg);
+    }
+
+    // Verify exactly one document was inserted
+    if (result.n !== 1) {
+        throw new Error(
+            `Expected to insert 1 document into '${collection}', but inserted ${result.n}. ` +
+            `Result: ${JSON.stringify(result)}`
+        );
+    }
+
+    return _id;
+}
+
+async function updateOne(client, collection, filter, update, options = {}) {
+    const updates = [{
+        q: filter,
+        u: update,
+        upsert: Boolean(options.upsert),
+    }];
+    if (options.arrayFilters) updates[0].arrayFilters = options.arrayFilters;
+    const result = await client.$runCommandRaw({
+        update: collection,
+        updates,
+    });
+    return result;
+}
+
+async function deleteOne(client, collection, filter) {
+    return client.$runCommandRaw({
+        delete: collection,
+        deletes: [
+            {
+                q: filter,
+                limit: 1,
+            },
+        ],
+    });
+}
+
+async function deleteMany(client, collection, filter) {
+    return client.$runCommandRaw({
+        delete: collection,
+        deletes: [
+            {
+                q: filter,
+                limit: 0,
+            },
+        ],
+    });
+}
+
+async function aggregate(client, collection, pipeline) {
+    const result = await client.$runCommandRaw({
+        aggregate: collection,
+        pipeline,
+        cursor: {},
+    });
+    return result?.cursor?.firstBatch || [];
+}
+
+// findMany/aggregate return ONLY the first batch (~101 docs); the drained variants below follow the cursor to completion so full scans don't silently truncate.
+const DRAIN_BATCH_SIZE = 1000;
+const MAX_DRAIN_BATCHES = 100000;
+
+function isCursorOpen(id) {
+    if (id === undefined || id === null) return false;
+    if (typeof id === 'number') return id !== 0;
+    if (typeof id === 'bigint') return id !== 0n;
+    // Extended JSON can surface a 64-bit cursor id as { $numberLong: "..." }.
+    if (typeof id === 'object' && id.$numberLong !== undefined) {
+        return id.$numberLong !== '0';
+    }
+    return String(id) !== '0';
+}
+
+async function drainCursor(client, collection, firstResult) {
+    const cursor = firstResult?.cursor || {};
+    const docs = [...(cursor.firstBatch || [])];
+    let cursorId = cursor.id;
+    let batches = 0;
+
+    while (isCursorOpen(cursorId) && batches < MAX_DRAIN_BATCHES) {
+        batches += 1;
+        const next = await client.$runCommandRaw({
+            getMore: cursorId,
+            collection,
+            batchSize: DRAIN_BATCH_SIZE,
+        });
+        const nextCursor = next?.cursor || {};
+        const nextBatch = nextCursor.nextBatch || [];
+        docs.push(...nextBatch);
+        cursorId = nextCursor.id;
+        if (nextBatch.length === 0) break;
+    }
+    return docs;
+}
+
+async function findManyDrained(client, collection, filter = {}, options = {}) {
+    const command = { find: collection, filter, batchSize: DRAIN_BATCH_SIZE };
+    if (options.projection) command.projection = options.projection;
+    if (options.sort) command.sort = options.sort;
+    const first = await client.$runCommandRaw(command);
+    return drainCursor(client, collection, first);
+}
+
+async function aggregateDrained(client, collection, pipeline, options = {}) {
+    const first = await client.$runCommandRaw({
+        aggregate: collection,
+        pipeline,
+        cursor: { batchSize: DRAIN_BATCH_SIZE },
+        ...options,
+    });
+    return drainCursor(client, collection, first);
+}
+
+module.exports = {
+    toObjectId,
+    toObjectIdArray,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    updateOne,
+    deleteOne,
+    deleteMany,
+    aggregate,
+    findManyDrained,
+    aggregateDrained,
+};
+