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

package/database/documentdb-utils.js

@@ -0,0 +1,136 @@
+const { ObjectId } = require('mongodb');
+
+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 new Error(`${errorMsg} - Duplicate key violation`);
+        }
+        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 || [];
+}
+
+module.exports = {
+    toObjectId,
+    toObjectIdArray,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    updateOne,
+    deleteOne,
+    deleteMany,
+    aggregate,
+};
+

package/database/encryption/README.md

@@ -130,7 +130,6 @@ const ENCRYPTION_SCHEMA = {
         fields: [
             'data.access_token', // OAuth access token
             'data.refresh_token', // OAuth refresh token
-            'data.domain', // Service domain
             'data.id_token', // OpenID Connect ID token
         ],
     },
@@ -267,6 +266,14 @@ const CORE_ENCRYPTION_SCHEMA = {
 -   Integration-specific sensitive data (use custom schema instead)
 -   Temporary/experimental encryption (use custom schema instead)
 
+#### After Adding Encrypted Fields
+
+After adding fields to `encryption-schema-registry.js`:
+
+1. **For MongoDB/PostgreSQL**: No code changes needed (automatic via Prisma Extension)
+2. **For DocumentDB**: Encryption is automatic via DocumentDBEncryptionService
+   (service reads from same registry)
+
 ## How It Works
 
 ### Write Operation (Create/Update)
@@ -403,6 +410,48 @@ return entities.map((e) => ({
 
 See `modules/repositories/module-repository-postgres.js` and `module-repository-mongo.js` for complete implementation examples using `_fetchCredential()` and `_fetchCredentialsBulk()` helper methods.
 
+## DocumentDB Encryption
+
+### Why DocumentDB Needs Manual Encryption
+
+DocumentDB repositories use `$runCommandRaw()` for MongoDB protocol compatibility, which bypasses Prisma Client Extensions. This means the automatic encryption extension does not apply.
+
+### DocumentDBEncryptionService
+
+For DocumentDB repositories, use `DocumentDBEncryptionService` to manually encrypt/decrypt documents before/after database operations.
+
+#### Usage Example
+
+```javascript
+const { DocumentDBEncryptionService } = require('../documentdb-encryption-service');
+const { insertOne, findOne } = require('../documentdb-utils');
+
+class MyRepositoryDocumentDB {
+    constructor() {
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    async create(data) {
+        // Encrypt before write
+        const encrypted = await this.encryptionService.encryptFields('ModelName', data);
+        const id = await insertOne(this.prisma, 'CollectionName', encrypted);
+
+        // Decrypt after read
+        const doc = await findOne(this.prisma, 'CollectionName', { _id: id });
+        const decrypted = await this.encryptionService.decryptFields('ModelName', doc);
+
+        return decrypted;
+    }
+}
+```
+
+#### Configuration
+
+Uses the same environment variables and Cryptor as the Prisma Extension:
+- `STAGE`: Bypasses encryption for dev/test/local
+- `KMS_KEY_ARN`: AWS KMS encryption (production)
+- `AES_KEY_ID` + `AES_KEY`: AES encryption (fallback)
+
 ## Usage Examples
 
 ### Repository Code (No Changes Needed!)