@friggframework/core 2.0.0-next.53 → 2.0.0-next.54

package/CLAUDE.md

@@ -27,7 +27,7 @@ This file provides guidance to Claude Code when working with the Frigg Framework
 `@friggframework/core` is the foundational package of the Frigg Framework, providing:
 
 - **IntegrationBase**: Base class all integrations extend
-- **Database Layer**: Multi-database support (MongoDB, PostgreSQL) with Prisma ORM
+- **Database Layer**: Multi-database support (MongoDB, DocumentDB, PostgreSQL) with Prisma ORM
 - **Encryption**: Transparent field-level encryption with AWS KMS or AES
 - **User Management**: Individual and organizational user support
 - **Module System**: API module loading and credential management
@@ -256,6 +256,7 @@ class MyIntegration extends IntegrationBase {
 - `health-check-repository.js` - Database health monitoring
 - `token-repository.js` - Authentication tokens
 - `websocket-connection-repository.js` - WebSocket connections
+- DocumentDB-enabled adapters mirror the MongoDB APIs but execute raw commands (`$runCommandRaw`, `$aggregateRaw`) for compatibility; encrypted models (e.g., credentials) still delegate reads to Prisma so the encryption extension can decrypt secrets transparently.
 
 **Use Cases**:
 - `check-database-health-use-case.js` - Database health checks

package/application/commands/integration-commands.js

@@ -38,7 +38,7 @@ function mapErrorToResponse(error) {
     };
 }
 
-function createIntegrationCommands({ integrationClass } = {}) {
+function createIntegrationCommands({ integrationClass }) {
     if (!integrationClass) {
         throw new Error('integrationClass is required');
     }

package/application/index.js

@@ -23,7 +23,7 @@ const {
  * const user = await commands.createUser({ username: 'user@example.com' });
  * const credential = await commands.createCredential({ userId: user.id, ... });
  */
-function createFriggCommands({ integrationClass } = {}) {
+function createFriggCommands({ integrationClass }) {
     // All commands use Frigg's default repositories and use cases
     const integrationCommands = createIntegrationCommands({ integrationClass });
 

package/credential/repositories/credential-repository-documentdb.js

@@ -0,0 +1,300 @@
+const { prisma } = require('../../database/prisma');
+const {
+    toObjectId,
+    fromObjectId,
+    findOne,
+    insertOne,
+    updateOne,
+    deleteOne,
+} = require('../../database/documentdb-utils');
+const {
+    CredentialRepositoryInterface,
+} = require('./credential-repository-interface');
+const { DocumentDBEncryptionService } = require('../../database/documentdb-encryption-service');
+
+/**
+ * Credential repository for DocumentDB.
+ * Uses DocumentDBEncryptionService for field-level encryption.
+ *
+ * Encrypted fields:
+ * - Credential.data.access_token
+ * - Credential.data.refresh_token
+ * - Credential.data.id_token
+ * - Credential.data.domain
+ *
+ * SECURITY CRITICAL: All OAuth credentials must be encrypted at rest.
+ *
+ * @see DocumentDBEncryptionService
+ * @see encryption-schema-registry.js
+ */
+class CredentialRepositoryDocumentDB extends CredentialRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    async findCredentialById(id) {
+        const objectId = toObjectId(id);
+        if (!objectId) return null;
+        const doc = await findOne(this.prisma, 'Credential', { _id: objectId });
+        if (!doc) return null;
+
+        // Decrypt sensitive fields using service
+        const decryptedCredential = await this.encryptionService.decryptFields('Credential', doc);
+        return this._mapCredentialById(decryptedCredential);
+    }
+
+    async updateAuthenticationStatus(credentialId, authIsValid) {
+        const objectId = toObjectId(credentialId);
+        if (!objectId) return { acknowledged: false, modifiedCount: 0 };
+        const result = await updateOne(
+            this.prisma,
+            'Credential',
+            { _id: objectId },
+            {
+                $set: { authIsValid, updatedAt: new Date() },
+            }
+        );
+        const modified = result?.nModified ?? result?.n ?? 0;
+        return { acknowledged: true, modifiedCount: modified };
+    }
+
+    async deleteCredentialById(credentialId) {
+        const objectId = toObjectId(credentialId);
+        if (!objectId) return { acknowledged: true, deletedCount: 0 };
+        const result = await deleteOne(this.prisma, 'Credential', { _id: objectId });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    async upsertCredential(credentialDetails) {
+        const { identifiers, details } = credentialDetails;
+        if (!identifiers) throw new Error('identifiers required to upsert credential');
+        if (!identifiers.user && !identifiers.userId) {
+            throw new Error('user or userId required in identifiers');
+        }
+        if (!identifiers.externalId) {
+            throw new Error(
+                'externalId required in identifiers to prevent credential collision. When multiple credentials exist for the same user, both userId and externalId are needed to uniquely identify which credential to update.'
+            );
+        }
+
+        const filter = this._buildIdentifierFilter(identifiers);
+        const existing = await findOne(this.prisma, 'Credential', filter);
+
+        const {
+            user,
+            userId,
+            authIsValid,
+            externalId,
+            ...oauthData
+        } = details || {};
+
+        const now = new Date();
+
+        if (existing) {
+            // Decrypt existing credential data first
+            const decryptedExisting = await this.encryptionService.decryptFields('Credential', existing);
+            const mergedData = { ...(decryptedExisting.data || {}), ...oauthData };
+
+            // Build update document
+            const updateDocument = {
+                userId: toObjectId(userId || user) || existing.userId || null,
+                externalId: externalId !== undefined ? externalId : existing.externalId,
+                authIsValid: authIsValid !== undefined ? authIsValid : existing.authIsValid,
+                data: mergedData,
+                updatedAt: now,
+            };
+
+            // Encrypt before storing
+            const encryptedUpdate = await this.encryptionService.encryptFields(
+                'Credential',
+                { data: updateDocument.data }
+            );
+
+            await updateOne(
+                this.prisma,
+                'Credential',
+                { _id: existing._id },
+                {
+                    $set: {
+                        userId: updateDocument.userId,
+                        externalId: updateDocument.externalId,
+                        authIsValid: updateDocument.authIsValid,
+                        data: encryptedUpdate.data,
+                        updatedAt: updateDocument.updatedAt,
+                    },
+                }
+            );
+
+            // Read back and decrypt
+            const updated = await findOne(this.prisma, 'Credential', { _id: existing._id });
+            const decryptedCredential = await this.encryptionService.decryptFields('Credential', updated);
+            return this._mapCredential(decryptedCredential);
+        }
+
+        // Build plain text document
+        const plainDocument = {
+            userId: toObjectId(userId || user || identifiers.user),
+            externalId: externalId !== undefined ? externalId : identifiers.externalId,
+            authIsValid: authIsValid ?? null,
+            data: oauthData,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        // Encrypt before storing
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'Credential',
+            plainDocument
+        );
+
+        const insertedId = await insertOne(this.prisma, 'Credential', encryptedDocument);
+
+        // Read back and decrypt
+        const created = await findOne(this.prisma, 'Credential', { _id: insertedId });
+        const decryptedCredential = await this.encryptionService.decryptFields('Credential', created);
+        return this._mapCredential(decryptedCredential);
+    }
+
+    async findCredential(filter) {
+        const query = this._buildFilter(filter);
+        const credential = await findOne(this.prisma, 'Credential', query);
+        if (!credential) return null;
+
+        // Decrypt sensitive fields using service
+        const decryptedCredential = await this.encryptionService.decryptFields('Credential', credential);
+        return this._mapCredential(decryptedCredential);
+    }
+
+    async updateCredential(credentialId, updates) {
+        const objectId = toObjectId(credentialId);
+        if (!objectId) return null;
+        const existing = await findOne(this.prisma, 'Credential', { _id: objectId });
+        if (!existing) return null;
+
+        const {
+            user,
+            userId,
+            authIsValid,
+            externalId,
+            ...oauthData
+        } = updates || {};
+
+        // Decrypt existing credential data first
+        const decryptedExisting = await this.encryptionService.decryptFields('Credential', existing);
+        const mergedData = { ...(decryptedExisting.data || {}), ...oauthData };
+
+        // Build update document
+        const updateDocument = {
+            userId: toObjectId(userId || user) || existing.userId || null,
+            externalId: externalId !== undefined ? externalId : existing.externalId,
+            authIsValid: authIsValid !== undefined ? authIsValid : existing.authIsValid,
+            data: mergedData,
+            updatedAt: new Date(),
+        };
+
+        // Encrypt before storing
+        const encryptedUpdate = await this.encryptionService.encryptFields(
+            'Credential',
+            { data: updateDocument.data }
+        );
+
+        await updateOne(
+            this.prisma,
+            'Credential',
+            { _id: objectId },
+            {
+                $set: {
+                    userId: updateDocument.userId,
+                    externalId: updateDocument.externalId,
+                    authIsValid: updateDocument.authIsValid,
+                    data: encryptedUpdate.data,
+                    updatedAt: updateDocument.updatedAt,
+                },
+            }
+        );
+
+        // Read back and decrypt
+        const updated = await findOne(this.prisma, 'Credential', { _id: objectId });
+        const decryptedCredential = await this.encryptionService.decryptFields('Credential', updated);
+        return this._mapCredential(decryptedCredential);
+    }
+
+    _buildIdentifierFilter(identifiers) {
+        const filter = {};
+        if (identifiers._id || identifiers.id) {
+            const idObj = toObjectId(identifiers._id || identifiers.id);
+            if (idObj) filter._id = idObj;
+        }
+        if (identifiers.user || identifiers.userId) {
+            const userObj = toObjectId(identifiers.user || identifiers.userId);
+            if (userObj) filter.userId = userObj;
+        }
+        if (identifiers.externalId !== undefined) {
+            filter.externalId = identifiers.externalId;
+        }
+        return filter;
+    }
+
+    _buildFilter(filter) {
+        const query = {};
+        if (!filter) return query;
+        if (filter.credentialId || filter.id) {
+            const idObj = toObjectId(filter.credentialId || filter.id);
+            if (idObj) query._id = idObj;
+        }
+        if (filter.user || filter.userId) {
+            const userObj = toObjectId(filter.user || filter.userId);
+            if (userObj) query.userId = userObj;
+        }
+        if (filter.externalId !== undefined) {
+            query.externalId = filter.externalId;
+        }
+        return query;
+    }
+
+    /**
+     * Map credential document to application format (without legacy fields)
+     * Used by findCredential, upsertCredential, updateCredential
+     * Matches MongoDB repository format
+     * @private
+     */
+    _mapCredential(doc) {
+        const data = doc?.data || {};
+        const id = fromObjectId(doc?._id);
+        const userId = fromObjectId(doc?.userId);
+        return {
+            id,
+            userId,
+            externalId: doc?.externalId ?? null,
+            authIsValid: doc?.authIsValid ?? null,
+            ...data,
+        };
+    }
+
+    /**
+     * Map credential document with legacy fields for findCredentialById
+     * Includes _id and user fields for backward compatibility
+     * Matches MongoDB repository format
+     * @private
+     */
+    _mapCredentialById(doc) {
+        const data = doc?.data || {};
+        const id = fromObjectId(doc?._id);
+        const userId = fromObjectId(doc?.userId);
+        return {
+            _id: id,
+            id,
+            user: userId,
+            userId,
+            externalId: doc?.externalId ?? null,
+            authIsValid: doc?.authIsValid ?? null,
+            ...data,
+        };
+    }
+}
+
+module.exports = { CredentialRepositoryDocumentDB };
+

package/credential/repositories/credential-repository-factory.js

@@ -2,6 +2,9 @@ const { CredentialRepositoryMongo } = require('./credential-repository-mongo');
 const {
     CredentialRepositoryPostgres,
 } = require('./credential-repository-postgres');
+const {
+    CredentialRepositoryDocumentDB,
+} = require('./credential-repository-documentdb');
 const config = require('../../database/config');
 
 /**
@@ -32,9 +35,12 @@ function createCredentialRepository() {
         case 'postgresql':
             return new CredentialRepositoryPostgres();
 
+        case 'documentdb':
+            return new CredentialRepositoryDocumentDB();
+
         default:
             throw new Error(
-                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'postgresql'`
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
             );
     }
 }
@@ -44,4 +50,5 @@ module.exports = {
     // Export adapters for direct testing
     CredentialRepositoryMongo,
     CredentialRepositoryPostgres,
+    CredentialRepositoryDocumentDB,
 };

package/database/config.js

@@ -10,7 +10,7 @@
  * 1. DB_TYPE environment variable (set for migration handlers)
  * 2. App definition (backend/index.js Definition.database configuration)
  *
- * @returns {'mongodb'|'postgresql'} Database type
+ * @returns {'mongodb'|'postgresql'|'documentdb'} Database type
  * @throws {Error} If database type cannot be determined or app definition missing
  */
 function getDatabaseType() {
@@ -93,7 +93,7 @@ function getDatabaseType() {
             return 'mongodb';
         }
         if (database.documentDB?.enable === true) {
-            return 'mongodb'; // DocumentDB is MongoDB-compatible
+            return 'documentdb';
         }
 
         throw new Error(
@@ -114,7 +114,7 @@ function getDatabaseType() {
 
 /**
  * Cached database type (lazy evaluation)
- * @type {'mongodb'|'postgresql'|null}
+ * @type {'mongodb'|'postgresql'|'documentdb'|null}
  */
 let cachedDbType = null;
 
@@ -140,7 +140,7 @@ module.exports = {
 /**
  * Lazy-evaluated database type determined from app definition
  * Only evaluates when accessed, preventing module load failures in test environments
- * @type {'mongodb'|'postgresql'}
+ * @type {'mongodb'|'postgresql'|'documentdb'}
  */
 Object.defineProperty(module.exports, 'DB_TYPE', {
     get() {