@friggframework/core 2.0.0-next.6 → 2.0.0-next.61

package/database/encryption/documentdb-encryption-service.md

@@ -0,0 +1,3575 @@
+# DocumentDB Encryption Service Implementation Guide
+
+**Status**: 🔴 **CRITICAL** - Security Vulnerability
+**Priority**: P0 - Immediate Action Required
+**Created**: 2025-01-13
+**Last Updated**: 2025-01-13
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Problem Statement](#problem-statement)
+3. [Architecture & Design](#architecture--design)
+4. [Technical Specification](#technical-specification)
+5. [Implementation Plan](#implementation-plan)
+6. [Code Examples](#code-examples)
+7. [Testing Strategy](#testing-strategy)
+8. [Migration Guide](#migration-guide)
+9. [Security Considerations](#security-considerations)
+10. [Maintenance & Future Work](#maintenance--future-work)
+11. [References](#references)
+
+---
+
+## Executive Summary
+
+### The Problem
+
+DocumentDB repositories use `$runCommandRaw()` for MongoDB protocol compatibility, which **bypasses Prisma Client Extensions**, including the encryption extension. This results in a **critical security vulnerability** where:
+
+-   ✅ **MongoDB/PostgreSQL**: Automatic encryption via Prisma Extension
+-   ❌ **DocumentDB**: OAuth credentials stored in **plain text**
+
+### The Solution
+
+Create `DocumentDBEncryptionService` - a centralized encryption service specifically designed for DocumentDB repositories that:
+
+-   Provides document-level encryption/decryption
+-   Handles nested field paths (e.g., `data.access_token`)
+-   Uses the same Cryptor and schema registry as Prisma Extension
+-   Maintains consistency with existing encryption architecture
+
+### Impact
+
+-   **Security**: OAuth credentials encrypted at rest in DocumentDB
+-   **Architecture**: DRY principle - single source of encryption logic
+-   **Consistency**: All DocumentDB repos use same encryption pattern
+-   **Compliance**: Meets production encryption requirements
+
+---
+
+## Problem Statement
+
+### Current Architecture (MongoDB/PostgreSQL)
+
+```
+Application Code (Use Cases)
+    ↓ works with plain data
+Repositories
+    ↓ uses Prisma queries
+Prisma Client + Extension (AUTOMATIC ENCRYPTION)
+    ↓ intercepts all queries
+FieldEncryptionService
+    ↓ encrypts/decrypts per field
+Cryptor (KMS or AES)
+    ↓
+Database (encrypted storage)
+```
+
+**How it works**:
+
+```javascript
+// MongoDB Repository - Automatic encryption
+await prisma.credential.create({
+    data: {
+        access_token: 'plain_secret', // ← Plain text in
+    },
+});
+// → Prisma Extension intercepts
+// → FieldEncryptionService.encryptField() called
+// → Stored as "keyId:iv:cipher:encKey" in database
+
+const cred = await prisma.credential.findFirst({ where: { id } });
+// ← Database returns "keyId:iv:cipher:encKey"
+// ← Prisma Extension intercepts
+// ← FieldEncryptionService.decryptField() called
+// ← Application receives { access_token: "plain_secret" }
+```
+
+### DocumentDB Architecture (Current - BROKEN)
+
+```
+Application Code (Use Cases)
+    ↓ works with plain data
+DocumentDB Repositories
+    ↓ uses $runCommandRaw
+Prisma Client (NO EXTENSION INTERCEPTION)
+    ↓ raw command bypasses all extensions
+Database (PLAIN TEXT STORAGE) ⚠️ SECURITY VULNERABILITY
+```
+
+**Why it's broken**:
+
+```javascript
+// DocumentDB Repository - NO encryption
+const oauthData = {
+    access_token: 'ya29.actual_google_token', // Plain text!
+    refresh_token: '1//0secret_refresh_token', // Plain text!
+};
+
+await prisma.$runCommandRaw({
+    insert: 'Credential',
+    documents: [{ data: oauthData }],
+});
+// ❌ Prisma Extension NEVER sees this command
+// ❌ FieldEncryptionService NEVER invoked
+// ❌ Stored in database as PLAIN TEXT
+```
+
+### Root Cause
+
+From Prisma documentation:
+
+> "$runCommandRaw is a low-level database access method. Prisma Client extensions do not apply to raw database access."
+
+**Why DocumentDB needs raw commands**:
+
+-   DocumentDB has MongoDB compatibility limitations
+-   Certain Prisma features don't work (transactions, some aggregations)
+-   Raw commands provide direct MongoDB protocol access
+
+### Current Repository Status
+
+| Repository                          | Encryption Status                                      | Security Risk                                |
+| ----------------------------------- | ------------------------------------------------------ | -------------------------------------------- |
+| **UserRepositoryDocumentDB**        | ✅ Has manual encryption for `hashword`                | Low - passwords protected                    |
+| **ModuleRepositoryDocumentDB**      | ⚠️ Has manual decryption for reads only                | Medium - assumes credentials encrypted       |
+| **CredentialRepositoryDocumentDB**  | ❌ **NO encryption on writes, NO decryption on reads** | 🔴 **CRITICAL - OAuth tokens in plain text** |
+| **IntegrationRepositoryDocumentDB** | ✅ No encrypted fields, OK                             | None                                         |
+
+---
+
+## Architecture & Design
+
+### Comparison: FieldEncryptionService vs DocumentDBEncryptionService
+
+| Aspect               | FieldEncryptionService                         | DocumentDBEncryptionService              |
+| -------------------- | ---------------------------------------------- | ---------------------------------------- |
+| **Purpose**          | Encrypt individual fields for Prisma Extension | Encrypt entire documents for raw queries |
+| **Invocation**       | Automatic (Prisma intercepts queries)          | Manual (repository calls explicitly)     |
+| **Scope**            | Single field at a time                         | Entire document with multiple fields     |
+| **Nested Fields**    | Handled by Prisma Extension traversal          | Must manually traverse field paths       |
+| **Integration**      | Via Prisma Client Extension                    | Direct import in repositories            |
+| **Query Types**      | `create()`, `update()`, `findFirst()`, etc.    | `$runCommandRaw()`, via documentdb-utils |
+| **Database Support** | MongoDB, PostgreSQL (via Prisma)               | DocumentDB (raw MongoDB protocol)        |
+| **Schema Registry**  | Used by Prisma Extension                       | Directly queries registry                |
+| **Error Handling**   | Prisma transaction rollback                    | Must handle in repository                |
+| **Testing**          | Integration tests with Prisma                  | Unit tests + repository tests            |
+
+### Proposed Architecture (DocumentDB - FIXED)
+
+```
+Application Code (Use Cases)
+    ↓ works with plain data
+DocumentDB Repositories
+    ↓ MANUALLY calls encryptFields()/decryptFields()
+DocumentDBEncryptionService
+    ↓ traverses field paths based on schema registry
+    ↓ encrypts/decrypts each field
+Cryptor (KMS or AES)
+    ↓
+Database (ENCRYPTED STORAGE) ✅ SECURE
+```
+
+### Architecture Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Application Layer (Use Cases)                                   │
+│  - Works with plain text data                                  │
+│  - Never sees encrypted values                                 │
+└──────────────────┬──────────────────────────────────────────────┘
+                   │
+      ┌────────────┴──────────────┐
+      │                           │
+      ▼ MongoDB/PostgreSQL        ▼ DocumentDB
+┌─────────────────────┐     ┌──────────────────────────┐
+│ Repository          │     │ Repository               │
+│  (plain text)       │     │  (plain text)            │
+└──────┬──────────────┘     └───┬──────────────────────┘
+       │                        │ Manually calls
+       │ Uses Prisma queries    │ encryptFields()/
+       ▼                        │ decryptFields()
+┌─────────────────────┐        ▼
+│ Prisma Client       │   ┌──────────────────────────────┐
+│  + Extension        │   │ DocumentDBEncryptionService  │
+│  (automatic)        │   │  - Traverses field paths     │
+└──────┬──────────────┘   │  - Calls Cryptor per field   │
+       │ Intercepts        └───┬──────────────────────────┘
+       │ queries                │
+       ▼                        │
+┌─────────────────────┐        │
+│ FieldEncryptionSvc  │◄───────┘ Both use Cryptor
+│  - Per-field logic  │
+└──────┬──────────────┘
+       │
+       ▼
+┌─────────────────────────────────────┐
+│ Cryptor (AWS KMS or AES)            │
+│  - Envelope encryption              │
+│  - Returns: "keyId:iv:cipher:encKey"│
+└──────┬──────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────┐
+│ Database (MongoDB/PostgreSQL/       │
+│           DocumentDB)               │
+│  - Stores encrypted strings         │
+└─────────────────────────────────────┘
+```
+
+### Design Principles
+
+1. **Consistency**: Same encryption format and Cryptor as Prisma Extension
+2. **Reusability**: Single service used by all DocumentDB repositories
+3. **Schema-Driven**: Uses `encryption-schema-registry.js` (same as Prisma)
+4. **Environment-Aware**: Respects STAGE-based bypass (dev/test/local)
+5. **Error-Tolerant**: Graceful handling of decryption failures
+6. **Testable**: Can be unit tested independently of repositories
+
+---
+
+## Technical Specification
+
+### Class Design
+
+```javascript
+/**
+ * Encryption service specifically for DocumentDB repositories
+ * that use $runCommandRaw and bypass Prisma Extensions.
+ *
+ * Provides document-level encryption/decryption,
+ * handling nested fields according to the encryption schema registry.
+ */
+class DocumentDBEncryptionService {
+    constructor()
+    _initializeCryptor()
+    async encryptFields(modelName, document)
+    async decryptFields(modelName, document)
+    async _encryptFieldPath(document, fieldPath, modelName)
+    async _decryptFieldPath(document, fieldPath, modelName)
+    _isEncryptedValue(value)
+}
+```
+
+### Method Specifications
+
+#### `constructor()`
+
+**Purpose**: Initialize the service and configure Cryptor
+
+**Behavior**:
+
+-   Calls `_initializeCryptor()` immediately
+-   Sets up `this.cryptor` and `this.enabled` properties
+
+**No parameters**
+
+---
+
+#### `_initializeCryptor()`
+
+**Purpose**: Initialize Cryptor with environment-based configuration
+
+**Logic**:
+
+```javascript
+1. Get STAGE from environment (default: 'development')
+2. If STAGE in ['dev', 'test', 'local']:
+   - Set this.cryptor = null
+   - Set this.enabled = false
+   - Return (bypass encryption)
+3. Check for KMS_KEY_ARN environment variable
+4. Check for AES_KEY_ID environment variable
+5. If neither present:
+   - Warn "No encryption keys configured"
+   - Set this.cryptor = null
+   - Set this.enabled = false
+   - Return
+6. Create Cryptor({ shouldUseAws: hasKMS })
+7. Set this.enabled = true
+```
+
+**Environment Variables Used**:
+
+-   `STAGE` or `NODE_ENV`: Determines bypass behavior
+-   `KMS_KEY_ARN`: AWS KMS key ARN (enables KMS encryption)
+-   `AES_KEY_ID`: AES key identifier (enables AES encryption)
+-   `AES_KEY`: AES encryption key (required if AES_KEY_ID present)
+
+**Matches**: Logic from `packages/core/database/prisma.js` lines 76-96
+
+---
+
+#### `async encryptFields(modelName, document)`
+
+**Purpose**: Encrypt fields in a document before storing to DocumentDB
+
+**Parameters**:
+
+-   `modelName` (string): Model name from schema registry (e.g., 'User', 'Credential')
+-   `document` (Object): Document to encrypt
+
+**Returns**: `Promise<Object>` - Document with encrypted fields
+
+**Algorithm**:
+
+```javascript
+1. If !this.enabled or !this.cryptor:
+   - Return document unchanged (bypass)
+2. If !document or typeof document !== 'object':
+   - Return document unchanged (invalid input)
+3. Get encrypted fields config from registry:
+   - encryptedFieldsConfig = getEncryptedFields(modelName)
+4. If no config or no fields defined:
+   - Return document unchanged (no encryption needed)
+5. Create shallow copy: result = { ...document }
+6. For each fieldPath in encryptedFieldsConfig.fields:
+   - await this._encryptFieldPath(result, fieldPath, modelName)
+7. Return result
+```
+
+**Error Handling**:
+
+-   Invalid inputs: Return unchanged
+-   Encryption errors: Propagate to caller (repository must handle)
+
+**Example**:
+
+```javascript
+const plainDoc = {
+    userId: '123',
+    data: {
+        access_token: 'plain_secret',
+        refresh_token: 'plain_refresh',
+    },
+};
+
+const encrypted = await service.encryptFields('Credential', plainDoc);
+// encrypted.data.access_token = "aes-key-1:iv:cipher:enckey"
+// encrypted.data.refresh_token = "aes-key-1:iv:cipher:enckey"
+```
+
+---
+
+#### `async decryptFields(modelName, document)`
+
+**Purpose**: Decrypt fields in a document after reading from DocumentDB
+
+**Parameters**:
+
+-   `modelName` (string): Model name from schema registry
+-   `document` (Object): Document to decrypt
+
+**Returns**: `Promise<Object>` - Document with decrypted fields
+
+**Algorithm**:
+
+```javascript
+1. If !this.enabled or !this.cryptor:
+   - Return document unchanged (bypass)
+2. If !document or typeof document !== 'object':
+   - Return document unchanged (invalid input)
+3. Get encrypted fields config from registry:
+   - encryptedFieldsConfig = getEncryptedFields(modelName)
+4. If no config or no fields defined:
+   - Return document unchanged (no decryption needed)
+5. Create shallow copy: result = { ...document }
+6. For each fieldPath in encryptedFieldsConfig.fields:
+   - await this._decryptFieldPath(result, fieldPath, modelName)
+7. Return result
+```
+
+**Error Handling**:
+
+-   Decryption failures: Set field to null (don't expose encrypted data)
+-   Log error with context
+
+**Example**:
+
+```javascript
+const encryptedDoc = {
+    userId: '123',
+    data: {
+        access_token: 'aes-key-1:iv:cipher:enckey',
+        refresh_token: 'aes-key-1:iv:cipher:enckey',
+    },
+};
+
+const decrypted = await service.decryptFields('Credential', encryptedDoc);
+// decrypted.data.access_token = "plain_secret"
+// decrypted.data.refresh_token = "plain_refresh"
+```
+
+---
+
+#### `async _encryptFieldPath(document, fieldPath, modelName)`
+
+**Purpose**: Encrypt a specific field path in a document (handles nested fields)
+
+**Parameters**:
+
+-   `document` (Object): Document to modify (mutated in place)
+-   `fieldPath` (string): Field path from schema registry (e.g., 'data.access_token')
+-   `modelName` (string): For error logging context
+
+**Algorithm**:
+
+```javascript
+1. Split fieldPath by '.': parts = fieldPath.split('.')
+2. Navigate to parent object:
+   - current = document
+   - For i from 0 to parts.length - 2:
+     - If !current[parts[i]]: return (path doesn't exist)
+     - current = current[parts[i]]
+3. Get field name: fieldName = parts[parts.length - 1]
+4. Get value: value = current[fieldName]
+5. Skip if already encrypted or empty:
+   - If !value or this._isEncryptedValue(value): return
+6. Convert to string if needed:
+   - stringValue = (typeof value === 'string') ? value : JSON.stringify(value)
+7. Encrypt using Cryptor:
+   - current[fieldName] = await this.cryptor.encrypt(stringValue)
+8. Catch errors:
+   - Log: "Failed to encrypt {modelName}.{fieldPath}: {error}"
+   - Throw error (repository must handle)
+```
+
+**Example Field Paths**:
+
+-   `hashword` → Encrypts `document.hashword`
+-   `data.access_token` → Encrypts `document.data.access_token`
+-   `data.refresh_token` → Encrypts `document.data.refresh_token`
+
+---
+
+#### `async _decryptFieldPath(document, fieldPath, modelName)`
+
+**Purpose**: Decrypt a specific field path in a document
+
+**Parameters**:
+
+-   `document` (Object): Document to modify (mutated in place)
+-   `fieldPath` (string): Field path from schema registry
+-   `modelName` (string): For error logging context
+
+**Algorithm**:
+
+```javascript
+1. Split fieldPath by '.': parts = fieldPath.split('.')
+2. Navigate to parent object:
+   - current = document
+   - For i from 0 to parts.length - 2:
+     - If !current[parts[i]]: return (path doesn't exist)
+     - current = current[parts[i]]
+3. Get field name: fieldName = parts[parts.length - 1]
+4. Get encrypted value: encryptedValue = current[fieldName]
+5. Skip if not encrypted format:
+   - If !encryptedValue or !this._isEncryptedValue(encryptedValue): return
+6. Decrypt using Cryptor:
+   - decryptedString = await this.cryptor.decrypt(encryptedValue)
+7. Try to parse as JSON:
+   - Try: current[fieldName] = JSON.parse(decryptedString)
+   - Catch: current[fieldName] = decryptedString (not JSON, return as string)
+8. Catch decryption errors:
+   - Log: "Failed to decrypt {modelName}.{fieldPath}: {error}"
+   - Set current[fieldName] = null (don't expose potentially corrupted data)
+```
+
+**Error Tolerance**:
+
+-   If decryption fails, set field to `null` instead of throwing
+-   Prevents exposing encrypted strings to application
+-   Logs error for debugging
+
+---
+
+#### `_isEncryptedValue(value)`
+
+**Purpose**: Check if a value is in encrypted format
+
+**Parameters**:
+
+-   `value` (any): Value to check
+
+**Returns**: `boolean` - True if value is encrypted
+
+**Logic**:
+
+```javascript
+1. If typeof value !== 'string': return false
+2. Split by ':': parts = value.split(':')
+3. Return parts.length >= 4
+```
+
+**Encrypted Format**: `"keyId:iv:cipher:encKey"` (envelope encryption)
+
+**Examples**:
+
+```javascript
+_isEncryptedValue('plain_text'); // false
+_isEncryptedValue('aes-key-1:iv123:cipher456:enckey789'); // true
+_isEncryptedValue(null); // false
+_isEncryptedValue({}); // false
+```
+
+---
+
+### Dependencies
+
+```javascript
+const { Cryptor } = require('../encrypt/Cryptor');
+const {
+    getEncryptedFields,
+} = require('./encryption/encryption-schema-registry');
+```
+
+**Cryptor**: Handles actual encryption/decryption (KMS or AES)
+**getEncryptedFields**: Returns encrypted field paths for a model
+
+---
+
+### Encrypted Fields (from Schema Registry)
+
+```javascript
+// From packages/core/database/encryption/encryption-schema-registry.js
+
+const ENCRYPTED_FIELDS = {
+    User: ['hashword'],
+    Credential: [
+        'data.access_token',
+        'data.refresh_token',
+        'data.id_token',
+        'data.domain',
+    ],
+    IntegrationMapping: ['mapping'],
+    Token: ['token'],
+};
+```
+
+**DocumentDBEncryptionService** will automatically encrypt/decrypt these fields when `encryptFields()`/`decryptFields()` is called with the corresponding model name.
+
+---
+
+## Implementation Plan
+
+### Phase 1: Create DocumentDBEncryptionService (New File)
+
+**Files to Create**:
+
+1. `packages/core/database/documentdb-encryption-service.js`
+2. `packages/core/database/__tests__/documentdb-encryption-service.test.js`
+
+**Implementation Checklist**:
+
+#### 1.1 Service Class (`documentdb-encryption-service.js`)
+
+-   [ ] Create file with standard file header comment
+-   [ ] Import dependencies: `Cryptor`, `getEncryptedFields`
+-   [ ] Create `DocumentDBEncryptionService` class
+-   [ ] Implement `constructor()` - calls `_initializeCryptor()`
+-   [ ] Implement `_initializeCryptor()` - matches `prisma.js` logic
+    -   [ ] Check STAGE environment variable
+    -   [ ] Implement bypass for dev/test/local
+    -   [ ] Check for KMS_KEY_ARN
+    -   [ ] Check for AES_KEY_ID
+    -   [ ] Create Cryptor with shouldUseAws flag
+    -   [ ] Set this.enabled flag
+-   [ ] Implement `encryptFields(modelName, document)`
+    -   [ ] Early returns for disabled/invalid input
+    -   [ ] Get encrypted fields from registry
+    -   [ ] Loop through field paths
+    -   [ ] Call `_encryptFieldPath()` for each
+-   [ ] Implement `decryptFields(modelName, document)`
+    -   [ ] Early returns for disabled/invalid input
+    -   [ ] Get encrypted fields from registry
+    -   [ ] Loop through field paths
+    -   [ ] Call `_decryptFieldPath()` for each
+-   [ ] Implement `_encryptFieldPath(document, fieldPath, modelName)`
+    -   [ ] Parse field path (split by '.')
+    -   [ ] Navigate to parent object
+    -   [ ] Check if already encrypted
+    -   [ ] Convert to string if needed
+    -   [ ] Call `this.cryptor.encrypt()`
+    -   [ ] Error handling with context
+-   [ ] Implement `_decryptFieldPath(document, fieldPath, modelName)`
+    -   [ ] Parse field path
+    -   [ ] Navigate to parent object
+    -   [ ] Check if encrypted format
+    -   [ ] Call `this.cryptor.decrypt()`
+    -   [ ] Try to parse as JSON
+    -   [ ] Error handling (set to null on failure)
+-   [ ] Implement `_isEncryptedValue(value)`
+    -   [ ] Type check (must be string)
+    -   [ ] Split by ':'
+    -   [ ] Check for 4+ parts
+-   [ ] Add JSDoc comments for all public methods
+-   [ ] Export: `module.exports = { DocumentDBEncryptionService };`
+
+#### 1.2 Service Tests (`__tests__/documentdb-encryption-service.test.js`)
+
+-   [ ] Create test file with describe block
+-   [ ] Mock dependencies: `Cryptor`, `getEncryptedFields`
+-   [ ] **Test Group: Initialization**
+    -   [ ] Test bypass in dev stage
+    -   [ ] Test bypass in test stage
+    -   [ ] Test bypass in local stage
+    -   [ ] Test enabled with KMS_KEY_ARN in production
+    -   [ ] Test enabled with AES_KEY_ID in production
+    -   [ ] Test disabled with no keys in production
+    -   [ ] Test KMS takes precedence over AES
+-   [ ] **Test Group: encryptFields()**
+    -   [ ] Test returns unchanged when disabled (dev stage)
+    -   [ ] Test returns unchanged for null document
+    -   [ ] Test returns unchanged for non-object document
+    -   [ ] Test returns unchanged when no encrypted fields in registry
+    -   [ ] Test encrypts User.hashword
+    -   [ ] Test encrypts Credential.data.access_token
+    -   [ ] Test encrypts Credential.data.refresh_token
+    -   [ ] Test encrypts multiple nested fields
+    -   [ ] Test skips already encrypted values
+    -   [ ] Test skips null values
+    -   [ ] Test skips non-existent paths
+    -   [ ] Test encrypts objects (JSON.stringify)
+    -   [ ] Test error handling (propagates error)
+-   [ ] **Test Group: decryptFields()**
+    -   [ ] Test returns unchanged when disabled
+    -   [ ] Test returns unchanged for null document
+    -   [ ] Test returns unchanged for non-object document
+    -   [ ] Test returns unchanged when no encrypted fields in registry
+    -   [ ] Test decrypts User.hashword
+    -   [ ] Test decrypts Credential.data.access_token
+    -   [ ] Test decrypts multiple nested fields
+    -   [ ] Test skips plain text values
+    -   [ ] Test skips null values
+    -   [ ] Test skips non-existent paths
+    -   [ ] Test parses JSON objects after decryption
+    -   [ ] Test handles non-JSON strings
+    -   [ ] Test error handling (sets field to null)
+-   [ ] **Test Group: \_isEncryptedValue()**
+    -   [ ] Test returns false for plain text
+    -   [ ] Test returns false for null
+    -   [ ] Test returns false for numbers
+    -   [ ] Test returns false for objects
+    -   [ ] Test returns false for short strings (< 4 parts)
+    -   [ ] Test returns true for encrypted format (4+ parts with colons)
+-   [ ] **Test Coverage Target**: >90% line coverage
+
+**Estimated Time**: 2-3 hours
+
+---
+
+### Phase 1.5: Fix Critical Issues from Code Review
+
+**Status**: ⚠️ CRITICAL - Must complete before Phase 2
+
+**Context**: After Phase 1 implementation and code review, three critical issues were identified that must be fixed before integrating the service into repositories. These issues address data corruption, silent failures, and testability concerns.
+
+**Code Review Summary**: Overall assessment 6/10 → 8/10 after fixes
+
+---
+
+#### Critical Issue #1: JSON.parse Corrupts Date Objects
+
+**Problem**:
+
+```javascript
+// Current implementation (lines 101, 147)
+const result = JSON.parse(JSON.stringify(document));
+```
+
+**Why it's critical**:
+
+-   `JSON.stringify()` converts Date objects to ISO strings
+-   `JSON.parse()` does NOT convert them back to Date objects
+-   OAuth tokens often have `expires_at` as Date objects
+-   This causes **silent data corruption** in production
+
+**Example of corruption**:
+
+```javascript
+const credential = {
+    data: { access_token: 'secret' },
+    expires_at: new Date('2025-12-31'), // Date object
+};
+
+const encrypted = await service.encryptFields('Credential', credential);
+// encrypted.expires_at is now "2025-12-31T00:00:00.000Z" (STRING, not Date)
+// This breaks any code expecting Date.getTime(), Date.toISOString(), etc.
+```
+
+**Fix**:
+
+```javascript
+// Use structuredClone (Node.js 17+)
+const result = structuredClone(document);
+```
+
+**Benefits of structuredClone**:
+
+-   ✅ Preserves Date objects
+-   ✅ Preserves RegExp objects
+-   ✅ Preserves Buffer objects
+-   ✅ Handles circular references
+-   ✅ Native Node.js function (no dependencies)
+
+**Files to Update**:
+
+-   `documentdb-encryption-service.js` lines 101, 147
+
+**Checklist**:
+
+-   [ ] Replace `JSON.parse(JSON.stringify(document))` in `encryptFields()` (line 101)
+-   [ ] Replace `JSON.parse(JSON.stringify(document))` in `decryptFields()` (line 147)
+-   [ ] Add test case: `it('preserves Date objects in documents')`
+-   [ ] Verify Node.js version supports structuredClone (>=17)
+
+**Estimated Time**: 5 minutes
+
+---
+
+#### Critical Issue #2: Decryption Failures Set to Null
+
+**Problem**:
+
+```javascript
+// Current implementation (_decryptFieldPath, line 258)
+catch (error) {
+    console.error('[DocumentDBEncryptionService] Failed to decrypt...', errorContext);
+    current[fieldName] = null;  // ❌ Silent data loss
+}
+```
+
+**Why it's critical**:
+
+-   **Silent credential loss** - Application continues with null tokens
+-   **Hard to debug** - Error logged but not propagated
+-   **Security risk** - Could mask key rotation issues or corrupted data
+-   **Cascade failures** - Null propagates until crash elsewhere
+
+**Real-world scenario**:
+
+```javascript
+// Encrypted credential in database (key rotated or corrupted)
+const credential = await findCredential(userId);
+// Decryption silently fails, field set to null
+
+// Application continues
+const api = new AsanaAPI({ token: credential.access_token });
+// ❌ Later crashes with "Cannot use null as token" far from root cause
+```
+
+**Why this is wrong**:
+
+-   Violates fail-fast principle (errors should be discovered immediately)
+-   Inconsistent with `encryptFields()` which throws errors
+-   Repository can't distinguish null data from decryption failure
+
+**Fix**:
+
+```javascript
+// Throw error immediately (fail fast)
+catch (error) {
+    console.error('[DocumentDBEncryptionService] Failed to decrypt...', errorContext);
+    throw new Error(`Decryption failed for ${modelName}.${fieldPath}: ${error.message}`);
+}
+```
+
+**Files to Update**:
+
+-   `documentdb-encryption-service.js` line 258
+-   `documentdb-encryption-service.test.js` update test "sets field to null on decryption error"
+
+**Checklist**:
+
+-   [ ] Remove `current[fieldName] = null;` from `_decryptFieldPath()` (line 258)
+-   [ ] Add `throw new Error(...)` with context
+-   [ ] Update test: change from `expect(result.hashword).toBeNull()` to `expect(...).rejects.toThrow()`
+-   [ ] Update test name: "throws error on decryption failure" (not "sets field to null")
+-   [ ] Verify all 56+ tests still pass
+
+**Estimated Time**: 10 minutes
+
+---
+
+#### Critical Issue #3: No Cryptor Dependency Injection
+
+**Problem**:
+
+```javascript
+// Current implementation (constructor, lines 24-26)
+constructor() {
+    this._initializeCryptor();  // ❌ Creates Cryptor internally
+}
+
+_initializeCryptor() {
+    this.cryptor = new Cryptor({ shouldUseAws });  // ❌ Hard-coded
+}
+```
+
+**Why it's critical**:
+
+-   **Repository tests break** - Can't mock encryption in Phase 2-4
+-   **Requires real keys** - Tests need AWS credentials or AES keys
+-   **Slower tests** - Real encryption is slower than mocks
+-   **Can't test error scenarios** - Can't simulate Cryptor failures
+
+**Impact on Phase 2 (UserRepositoryDocumentDB tests)**:
+
+```javascript
+describe('UserRepositoryDocumentDB', () => {
+    it('encrypts hashword before saving', async () => {
+        // ❌ PROBLEM: Can't mock DocumentDBEncryptionService's Cryptor
+        const service = new DocumentDBEncryptionService();
+        // Tries to create real Cryptor - tests fail without keys
+
+        const repo = new UserRepositoryDocumentDB({
+            encryptionService: service,
+        });
+        await repo.createUser({ hashword: 'password' });
+        // ❌ Real KMS/AES encryption happens in tests
+    });
+});
+```
+
+**Fix**:
+
+```javascript
+class DocumentDBEncryptionService {
+    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();
+        }
+    }
+}
+```
+
+**Usage**:
+
+```javascript
+// In tests (with mock)
+const mockCryptor = {
+    encrypt: jest.fn().mockResolvedValue('encrypted'),
+    decrypt: jest.fn().mockResolvedValue('decrypted'),
+};
+const service = new DocumentDBEncryptionService({ cryptor: mockCryptor });
+
+// In production (uses environment config)
+const service = new DocumentDBEncryptionService();
+```
+
+**Files to Update**:
+
+-   `documentdb-encryption-service.js` constructor
+-   `documentdb-encryption-service.test.js` add dependency injection test
+
+**Checklist**:
+
+-   [ ] Change constructor signature: `constructor({ cryptor = null } = {})`
+-   [ ] Add conditional logic: if cryptor provided, use it; else call `_initializeCryptor()`
+-   [ ] Set `this.enabled = true` when cryptor injected
+-   [ ] Add test: `it('accepts injected Cryptor for testing')`
+-   [ ] Verify injection test passes
+-   [ ] Verify all existing tests still pass
+
+**Estimated Time**: 15 minutes
+
+---
+
+#### Phase 1.5 Summary
+
+**Total Changes**:
+
+-   3 files modified
+-   5 lines of code changed (service implementation)
+-   3 new/updated test cases
+-   0 breaking changes (backward compatible)
+
+**Total Time**: ~30 minutes
+
+**Success Criteria**:
+
+-   ✅ All 56+ tests pass
+-   ✅ Date objects preserved in documents
+-   ✅ Decryption failures throw errors
+-   ✅ Cryptor can be injected for testing
+-   ✅ 100% code coverage maintained
+-   ✅ Code review assessment improves from 6/10 to 8/10
+
+**Validation**:
+
+```javascript
+// Test 1: Date preservation
+const doc = { data: { token: 'secret' }, createdAt: new Date() };
+const encrypted = await service.encryptFields('Model', doc);
+expect(encrypted.createdAt).toBeInstanceOf(Date); // ✅ Must pass
+
+// Test 2: Decryption error throws
+const corrupted = { data: { token: 'corrupted_encrypted_value' } };
+await expect(service.decryptFields('Model', corrupted)).rejects.toThrow(
+    'Decryption failed'
+); // ✅ Must pass
+
+// Test 3: Dependency injection
+const mockCryptor = { encrypt: jest.fn(), decrypt: jest.fn() };
+const service = new DocumentDBEncryptionService({ cryptor: mockCryptor });
+expect(service.cryptor).toBe(mockCryptor); // ✅ Must pass
+```
+
+**Next Step**: After Phase 1.5 completion, proceed to Phase 2 (Refactor UserRepositoryDocumentDB)
+
+---
+
+### Phase 2: Refactor UserRepositoryDocumentDB
+
+**File**: `packages/core/user/repositories/user-repository-documentdb.js`
+
+**Changes Checklist**:
+
+-   [ ] Import DocumentDBEncryptionService at top of file
+-   [ ] **Remove existing encryption methods** (lines 24-148):
+    -   [ ] Remove `_initializeCryptor()` method
+    -   [ ] Remove `_encryptField()` method
+    -   [ ] Remove `_decryptField()` method
+    -   [ ] Remove `_isEncryptedValue()` method
+    -   [ ] Remove `_encryptHashword()` method
+    -   [ ] Remove `_decryptHashword()` method
+-   [ ] **Update constructor**:
+    -   [ ] Add: `this.encryptionService = new DocumentDBEncryptionService();`
+    -   [ ] Remove: `this._initializeCryptor();`
+-   [ ] **Update `createIndividualUser()` method** (around line 183):
+    -   [ ] After building document, before insertOne():
+        ```javascript
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'User',
+            document
+        );
+        const insertedId = await insertOne(
+            this.prisma,
+            'User',
+            encryptedDocument
+        );
+        ```
+    -   [ ] After findOne(), before \_mapUser():
+        ```javascript
+        const decryptedUser = await this.encryptionService.decryptFields(
+            'User',
+            created
+        );
+        return this._mapUser(decryptedUser);
+        ```
+-   [ ] **Update `createOrganizationUser()` method**:
+    -   [ ] No changes needed (no encrypted fields for organization users)
+-   [ ] **Update `findIndividualUserById()` method** (around line 165):
+    -   [ ] After findOne():
+        ```javascript
+        const decryptedUser = await this.encryptionService.decryptFields(
+            'User',
+            doc
+        );
+        return this._mapUser(decryptedUser);
+        ```
+-   [ ] **Update `findIndividualUserByUsername()` method**:
+    -   [ ] Same pattern: decrypt after findOne()
+-   [ ] **Update `findIndividualUserByEmail()` method**:
+    -   [ ] Same pattern: decrypt after findOne()
+-   [ ] **Update `findIndividualUserByAppUserId()` method**:
+    -   [ ] Same pattern: decrypt after findOne()
+-   [ ] **Update `findIndividualUserById()` method**:
+    -   [ ] Same pattern: decrypt after findOne()
+-   [ ] **Update `updateIndividualUser()` method** (around line 303):
+    -   [ ] After preparing update payload, encrypt before updateOne():
+        ```javascript
+        const encryptedPayload = await this.encryptionService.encryptFields(
+            'User',
+            payload
+        );
+        await updateOne(
+            this.prisma,
+            'User',
+            { _id: objectId, type: 'INDIVIDUAL' },
+            { $set: encryptedPayload }
+        );
+        ```
+    -   [ ] After findOne(), decrypt before \_mapUser():
+        ```javascript
+        const decryptedUser = await this.encryptionService.decryptFields(
+            'User',
+            updated
+        );
+        return this._mapUser(decryptedUser);
+        ```
+-   [ ] **Update `updateOrganizationUser()` method**:
+    -   [ ] No changes needed (no encrypted fields)
+-   [ ] Verify no references to old encryption methods remain
+-   [ ] Run linter to check for issues
+-   [ ] Test locally
+
+**Estimated Time**: 1 hour
+
+---
+
+### Phase 3: Refactor ModuleRepositoryDocumentDB
+
+**File**: `packages/core/modules/repositories/module-repository-documentdb.js`
+
+**Changes Checklist**:
+
+-   [ ] Import DocumentDBEncryptionService at top of file
+-   [ ] **Remove existing encryption methods** (lines 22-117):
+    -   [ ] Remove `_initializeCryptor()` method
+    -   [ ] Remove `_encryptField()` method
+    -   [ ] Remove `_decryptField()` method
+    -   [ ] Remove `_isEncryptedValue()` method
+    -   [ ] Remove `_decryptCredentialData()` method
+-   [ ] **Update constructor**:
+    -   [ ] Add: `this.encryptionService = new DocumentDBEncryptionService();`
+    -   [ ] Remove: `this._initializeCryptor();`
+-   [ ] **Update `_fetchCredential()` method** (around line 241):
+    -   [ ] After findOne(), before returning:
+        ```javascript
+        const decryptedCredential = await this.encryptionService.decryptFields(
+            'Credential',
+            rawCredential
+        );
+        return {
+            id: fromObjectId(decryptedCredential._id),
+            userId: fromObjectId(decryptedCredential.userId),
+            externalId: decryptedCredential.externalId ?? null,
+            authIsValid: decryptedCredential.authIsValid ?? null,
+            createdAt: decryptedCredential.createdAt,
+            updatedAt: decryptedCredential.updatedAt,
+            data: decryptedCredential.data,
+        };
+        ```
+-   [ ] **Update `_fetchCredentialsBulk()` method** (around line 280):
+    -   [ ] Inside the map function for each credential:
+        ```javascript
+        const decryptedCredential = await this.encryptionService.decryptFields(
+            'Credential',
+            rawCredential
+        );
+        return this._convertCredentialIds({
+            id: fromObjectId(decryptedCredential._id),
+            // ... rest of mapping
+            data: decryptedCredential.data,
+        });
+        ```
+-   [ ] Verify no references to old encryption methods remain
+-   [ ] Run linter to check for issues
+-   [ ] Test locally
+
+**Note**: ModuleRepository doesn't create/update credentials, only reads them. It relies on CredentialRepository for writes.
+
+**Estimated Time**: 1 hour
+
+---
+
+### Phase 4: Fix CredentialRepositoryDocumentDB (CRITICAL)
+
+**File**: `packages/core/credential/repositories/credential-repository-documentdb.js`
+
+**Critical Priority**: This is the security vulnerability fix
+
+**Changes Checklist**:
+
+-   [ ] Import DocumentDBEncryptionService at top of file
+-   [ ] **Update constructor**:
+    -   [ ] Add: `this.encryptionService = new DocumentDBEncryptionService();`
+-   [ ] **Fix `upsertCredential()` method** (around line 50):
+
+    -   [ ] **Current problematic code**:
+
+        ```javascript
+        const { user, userId, authIsValid, externalId, ...oauthData } =
+            details || {};
+        // oauthData contains PLAIN TEXT: access_token, refresh_token, etc.
+
+        const document = {
+            data: oauthData, // ❌ STORED AS PLAIN TEXT
+        };
+        await insertOne(this.prisma, 'Credential', document);
+        ```
+
+    -   [ ] **Replace with ENCRYPTED version**:
+
+        ```javascript
+        const { user, userId, authIsValid, externalId, ...oauthData } =
+            details || {};
+
+        // Build plain text document
+        const plainDocument = {
+            userId: toObjectId(userId || user),
+            externalId: externalId ?? null,
+            authIsValid: authIsValid ?? true,
+            data: oauthData, // Still plain text at this point
+            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);
+        ```
+
+    -   [ ] **For UPDATE case** (when credential exists):
+
+        ```javascript
+        // Merge existing data with new data
+        const existingData = existing.data || {};
+        const mergedData = { ...existingData, ...oauthData };
+
+        // Build update document
+        const updateDocument = {
+            data: mergedData,
+            authIsValid: authIsValid ?? existing.authIsValid,
+            updatedAt: now,
+        };
+
+        // ✅ ENCRYPT before storing
+        const encryptedUpdate = await this.encryptionService.encryptFields(
+            'Credential',
+            { data: updateDocument.data } // Only encrypt the data field
+        );
+
+        await updateOne(
+            this.prisma,
+            'Credential',
+            { _id: existing._id },
+            {
+                $set: {
+                    data: encryptedUpdate.data,
+                    authIsValid: updateDocument.authIsValid,
+                    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);
+        ```
+
+-   [ ] **Fix `_mapCredential()` method** (around line 192):
+    -   [ ] **Current problematic code**:
+        ```javascript
+        _mapCredential(doc) {
+            const data = doc?.data || {};
+            return {
+                id: fromObjectId(doc._id),
+                userId: fromObjectId(doc.userId),
+                externalId: doc.externalId ?? null,
+                authIsValid: doc.authIsValid ?? null,
+                ...data  // ❌ Could be encrypted strings
+            };
+        }
+        ```
+    -   [ ] **Note**: If we decrypt in `upsertCredential()` before calling `_mapCredential()`, this method doesn't need changes. But for safety:
+        ```javascript
+        _mapCredential(doc) {
+            // Assume doc is already decrypted by caller
+            // (upsertCredential, findCredential should decrypt before calling this)
+            const data = doc?.data || {};
+            return {
+                id: fromObjectId(doc._id),
+                userId: fromObjectId(doc.userId),
+                externalId: doc.externalId ?? null,
+                authIsValid: doc.authIsValid ?? null,
+                ...data  // Already decrypted
+            };
+        }
+        ```
+-   [ ] **Fix `findCredential()` method** (if exists):
+
+    -   [ ] After findOne(), decrypt:
+
+        ```javascript
+        const doc = await findOne(this.prisma, 'Credential', filter);
+        if (!doc) return null;
+
+        const decryptedDoc = await this.encryptionService.decryptFields(
+            'Credential',
+            doc
+        );
+        return this._mapCredential(decryptedDoc);
+        ```
+
+-   [ ] **Fix `findManyCredentials()` method** (if exists):
+
+    -   [ ] After findMany(), decrypt each:
+
+        ```javascript
+        const docs = await findMany(this.prisma, 'Credential', filter);
+
+        const decryptedDocs = await Promise.all(
+            docs.map((doc) =>
+                this.encryptionService.decryptFields('Credential', doc)
+            )
+        );
+
+        return decryptedDocs.map((doc) => this._mapCredential(doc));
+        ```
+
+-   [ ] Add JSDoc comments explaining encryption
+-   [ ] Verify all credential read/write operations are covered
+-   [ ] Run linter
+-   [ ] Test locally with real OAuth flow
+
+**Security Verification**:
+
+-   [ ] Create test credential with `access_token: "test_secret"`
+-   [ ] Query database directly (bypass repository)
+-   [ ] Verify stored value is encrypted format: `"keyId:iv:cipher:encKey"`
+-   [ ] Verify repository returns decrypted value: `"test_secret"`
+
+**Estimated Time**: 1.5 hours
+
+---
+
+### Phase 5: Add Comprehensive Tests
+
+#### 5.1 User Repository Encryption Tests
+
+**File**: `packages/core/user/repositories/__tests__/user-repository-documentdb-encryption.test.js`
+
+**Test Coverage Checklist**:
+
+-   [ ] Create test file with describe block
+-   [ ] Mock DocumentDBEncryptionService
+-   [ ] **Test Group: Encryption on Write**
+    -   [ ] Test `createIndividualUser()` encrypts hashword before insert
+    -   [ ] Test `updateIndividualUser()` encrypts hashword before update
+    -   [ ] Verify encrypted format in database (use direct query)
+    -   [ ] Verify plain text never stored
+-   [ ] **Test Group: Decryption on Read**
+    -   [ ] Test `findIndividualUserById()` returns decrypted hashword
+    -   [ ] Test `findIndividualUserByUsername()` returns decrypted hashword
+    -   [ ] Test `findIndividualUserByEmail()` returns decrypted hashword
+    -   [ ] Verify application receives plain text
+-   [ ] **Test Group: Stage-Based Bypass**
+    -   [ ] Test encryption bypassed in dev stage
+    -   [ ] Test encryption bypassed in test stage
+    -   [ ] Test encryption bypassed in local stage
+    -   [ ] Test encryption enabled in production stage
+-   [ ] **Test Group: Edge Cases**
+    -   [ ] Test null hashword handling
+    -   [ ] Test undefined hashword handling
+    -   [ ] Test empty string hashword
+    -   [ ] Test already encrypted hashword (idempotent)
+-   [ ] **Test Group: Error Handling**
+    -   [ ] Test encryption service throws error
+    -   [ ] Test decryption service throws error
+    -   [ ] Verify error propagation to use case
+-   [ ] Run tests: `npm test user-repository-documentdb-encryption.test.js`
+
+**Estimated Time**: 1.5 hours
+
+---
+
+#### 5.2 Module Repository Encryption Tests
+
+**File**: `packages/core/modules/repositories/__tests__/module-repository-documentdb-encryption.test.js`
+
+**Test Coverage Checklist**:
+
+-   [ ] Create test file with describe block
+-   [ ] Mock DocumentDBEncryptionService
+-   [ ] Mock credential data in database (pre-encrypted)
+-   [ ] **Test Group: Credential Decryption**
+    -   [ ] Test `_fetchCredential()` decrypts credential data
+    -   [ ] Test `_fetchCredentialsBulk()` decrypts multiple credentials
+    -   [ ] Verify nested field decryption (data.access_token)
+    -   [ ] Verify multiple field decryption (access_token, refresh_token, id_token)
+-   [ ] **Test Group: Integration with Entities**
+    -   [ ] Test `findEntityById()` returns entity with decrypted credential
+    -   [ ] Test `findEntitiesByUserId()` returns entities with decrypted credentials
+    -   [ ] Test `findEntitiesByUserIdAndModuleName()` decrypts credentials
+-   [ ] **Test Group: Error Handling**
+    -   [ ] Test corrupted encrypted data (decryption fails)
+    -   [ ] Test missing credential (null credential)
+    -   [ ] Verify graceful degradation
+-   [ ] **Test Group: Performance**
+    -   [ ] Test bulk decryption of 10 credentials
+    -   [ ] Verify parallel decryption (not sequential)
+-   [ ] Run tests: `npm test module-repository-documentdb-encryption.test.js`
+
+**Estimated Time**: 1.5 hours
+
+---
+
+#### 5.3 Credential Repository Encryption Tests (NEW - CRITICAL)
+
+**File**: `packages/core/credential/repositories/__tests__/credential-repository-documentdb-encryption.test.js`
+
+**Test Coverage Checklist**:
+
+-   [ ] Create test file with describe block
+-   [ ] Mock DocumentDBEncryptionService
+-   [ ] Setup DocumentDB test database
+-   [ ] **Test Group: Encryption on Upsert (INSERT)**
+
+    -   [ ] Test encrypts access_token before insert
+    -   [ ] Test encrypts refresh_token before insert
+    -   [ ] Test encrypts id_token before insert
+    -   [ ] Test encrypts domain before insert
+    -   [ ] **Verify encrypted format in database**:
+
+        ```javascript
+        // Direct database query (bypass repository)
+        const rawDoc = await prisma.$runCommandRaw({
+            find: 'Credential',
+            filter: { userId: toObjectId(userId) },
+        });
+        const storedToken = rawDoc.cursor.firstBatch[0].data.access_token;
+
+        // Must match encrypted format
+        expect(storedToken).toMatch(/^[^:]+:[^:]+:[^:]+:[^:]+$/);
+        expect(storedToken).not.toBe('plain_secret');
+        ```
+
+-   [ ] **Test Group: Encryption on Upsert (UPDATE)**
+    -   [ ] Test existing credential update encrypts new tokens
+    -   [ ] Test merges existing encrypted data with new encrypted data
+    -   [ ] Test updates preserve other credential fields
+-   [ ] **Test Group: Decryption on Read**
+
+    -   [ ] Test `upsertCredential()` returns decrypted credential
+    -   [ ] Test `findCredential()` returns decrypted credential (if exists)
+    -   [ ] Test `_mapCredential()` receives decrypted data
+    -   [ ] **Verify plain text returned to application**:
+
+        ```javascript
+        const credential = await repository.upsertCredential({
+            userId,
+            externalId,
+            access_token: 'plain_secret',
+            refresh_token: 'plain_refresh',
+        });
+
+        expect(credential.access_token).toBe('plain_secret');
+        expect(credential.refresh_token).toBe('plain_refresh');
+        ```
+
+-   [ ] **Test Group: Integration Flow**
+    -   [ ] Test full flow: insert → read → verify
+    -   [ ] Test full flow: insert → update → read → verify
+    -   [ ] Test multiple credentials per user
+    -   [ ] Test credential retrieval by externalId
+-   [ ] **Test Group: Security Validation**
+    -   [ ] Test KMS encryption in production stage
+    -   [ ] Test AES encryption when KMS unavailable
+    -   [ ] Test bypass in dev/test/local stages
+    -   [ ] Test plain text never exposed in logs
+-   [ ] **Test Group: Error Handling**
+    -   [ ] Test encryption service throws error on insert
+    -   [ ] Test decryption service throws error on read
+    -   [ ] Test partial credential data (missing fields)
+    -   [ ] Test null values for optional fields
+-   [ ] **Test Group: Edge Cases**
+    -   [ ] Test empty oauth data
+    -   [ ] Test very large token values (>1KB)
+    -   [ ] Test special characters in tokens
+    -   [ ] Test unicode in tokens
+-   [ ] Run tests: `npm test credential-repository-documentdb-encryption.test.js`
+
+**Security Test Example**:
+
+```javascript
+describe('Security - Encryption Verification', () => {
+    it('stores access_token in encrypted format in database', async () => {
+        const userId = new ObjectId();
+        const externalId = 'test-external-123';
+        const plainToken = 'ya29.actual_google_token_here';
+
+        // Create credential via repository
+        await credentialRepo.upsertCredential({
+            userId: fromObjectId(userId),
+            externalId,
+            access_token: plainToken,
+        });
+
+        // Query database directly (bypass repository and encryption)
+        const rawResult = await prisma.$runCommandRaw({
+            find: 'Credential',
+            filter: { userId, externalId },
+        });
+
+        const storedCredential = rawResult.cursor.firstBatch[0];
+        const storedToken = storedCredential.data.access_token;
+
+        // CRITICAL: Verify encrypted format
+        expect(storedToken).not.toBe(plainToken); // Must not be plain text
+        expect(storedToken).toMatch(/^[^:]+:[^:]+:[^:]+:[^:]+$/); // Must be "keyId:iv:cipher:encKey"
+
+        // Verify repository returns decrypted value
+        const retrieved = await credentialRepo.findCredential({
+            userId,
+            externalId,
+        });
+        expect(retrieved.access_token).toBe(plainToken); // Must be decrypted
+    });
+});
+```
+
+**Estimated Time**: 2 hours
+
+---
+
+### Phase 6: Apply to Both Locations
+
+**Dual Location Rule**: All changes must be applied to BOTH:
+
+1. **Development**: `/Users/danielklotz/projects/lefthook/frontify--frigg/tmp/frigg/packages/core/`
+2. **Runtime**: `/Users/danielklotz/projects/lefthook/frontify--frigg/backend/node_modules/@friggframework/core/`
+
+**Files to Update in Both Locations**:
+
+-   [ ] `database/documentdb-encryption-service.js` (NEW)
+-   [ ] `database/__tests__/documentdb-encryption-service.test.js` (NEW)
+-   [ ] `user/repositories/user-repository-documentdb.js`
+-   [ ] `user/repositories/__tests__/user-repository-documentdb-encryption.test.js` (NEW)
+-   [ ] `modules/repositories/module-repository-documentdb.js`
+-   [ ] `modules/repositories/__tests__/module-repository-documentdb-encryption.test.js` (NEW)
+-   [ ] `credential/repositories/credential-repository-documentdb.js`
+-   [ ] `credential/repositories/__tests__/credential-repository-documentdb-encryption.test.js` (NEW)
+
+**Verification Steps**:
+
+For each file:
+
+-   [ ] Copy from `/tmp/frigg/` to `/backend/node_modules/@friggframework/`
+-   [ ] Verify file checksums match
+-   [ ] Run `diff` to confirm identical content
+-   [ ] Check file permissions
+
+**Script to Automate** (optional):
+
+```bash
+#!/bin/bash
+# sync-documentdb-encryption.sh
+
+SOURCE="/Users/danielklotz/projects/lefthook/frontify--frigg/tmp/frigg/packages/core"
+DEST="/Users/danielklotz/projects/lefthook/frontify--frigg/backend/node_modules/@friggframework/core"
+
+FILES=(
+    "database/documentdb-encryption-service.js"
+    "database/__tests__/documentdb-encryption-service.test.js"
+    "user/repositories/user-repository-documentdb.js"
+    "user/repositories/__tests__/user-repository-documentdb-encryption.test.js"
+    "modules/repositories/module-repository-documentdb.js"
+    "modules/repositories/__tests__/module-repository-documentdb-encryption.test.js"
+    "credential/repositories/credential-repository-documentdb.js"
+    "credential/repositories/__tests__/credential-repository-documentdb-encryption.test.js"
+)
+
+for file in "${FILES[@]}"; do
+    cp "$SOURCE/$file" "$DEST/$file"
+    echo "✅ Synced: $file"
+done
+
+echo "🎉 All files synced successfully"
+```
+
+**Estimated Time**: 30 minutes
+
+---
+
+### Phase 7: Validation & Testing
+
+#### 7.1 Run Test Suites
+
+**Test Execution Checklist**:
+
+-   [ ] **Run DocumentDB encryption service tests**:
+
+    ```bash
+    cd /Users/danielklotz/projects/lefthook/frontify--frigg/tmp/frigg
+    npm test packages/core/database/__tests__/documentdb-encryption-service.test.js
+    ```
+
+    -   [ ] Verify all tests pass
+    -   [ ] Check coverage >90%
+
+-   [ ] **Run User repository encryption tests**:
+
+    ```bash
+    npm test packages/core/user/repositories/__tests__/user-repository-documentdb-encryption.test.js
+    ```
+
+    -   [ ] Verify all tests pass
+
+-   [ ] **Run Module repository encryption tests**:
+
+    ```bash
+    npm test packages/core/modules/repositories/__tests__/module-repository-documentdb-encryption.test.js
+    ```
+
+    -   [ ] Verify all tests pass
+
+-   [ ] **Run Credential repository encryption tests** (CRITICAL):
+
+    ```bash
+    npm test packages/core/credential/repositories/__tests__/credential-repository-documentdb-encryption.test.js
+    ```
+
+    -   [ ] Verify all tests pass
+    -   [ ] Verify security test passes (encrypted format verification)
+
+-   [ ] **Run all repository tests**:
+
+    ```bash
+    npm test -- --testPathPattern=documentdb
+    ```
+
+    -   [ ] Verify no regressions
+
+-   [ ] **Run full test suite**:
+    ```bash
+    npm test
+    ```
+    -   [ ] Verify all tests pass
+    -   [ ] Check for no unexpected failures
+
+---
+
+#### 7.2 Manual Verification
+
+**Local Environment Setup**:
+
+-   [ ] Start MongoDB (DocumentDB simulation):
+
+    ```bash
+    cd /Users/danielklotz/projects/lefthook/frontify--frigg/backend
+    npm run docker:start
+    ```
+
+-   [ ] Verify MongoDB is running:
+
+    ```bash
+    docker ps | grep mongo
+    ```
+
+-   [ ] Set environment variables for encryption:
+
+    ```bash
+    export STAGE=production
+    export AES_KEY_ID=local-test-key
+    export AES_KEY=01234567890123456789012345678901  # 32 chars
+    ```
+
+-   [ ] Start backend:
+    ```bash
+    cd /Users/danielklotz/projects/lefthook/frontify--frigg/backend
+    npm run frigg:start
+    ```
+
+**Manual Test: Credential Creation**
+
+-   [ ] Create user and get token:
+
+    ```bash
+    curl -X POST http://localhost:3000/user/create \
+      -H "Content-Type: application/json" \
+      -d '{"username":"test@test.com","password":"test"}' \
+      -o /tmp/token.json
+
+    TOKEN=$(jq -r '.token' /tmp/token.json)
+    echo "Token: $TOKEN"
+    ```
+
+-   [ ] Create OAuth credential (if endpoint exists, else use Asana OAuth flow):
+    ```bash
+    # Trigger OAuth flow through application
+    # Then verify credential was created encrypted
+    ```
+
+**Manual Test: Database Verification**
+
+-   [ ] Connect to MongoDB:
+
+    ```bash
+    docker exec -it $(docker ps -q -f name=mongo) mongosh
+    ```
+
+-   [ ] Query credential:
+
+    ```javascript
+    use frigg
+    db.Credential.findOne()
+    ```
+
+-   [ ] **CRITICAL VERIFICATION**:
+
+    ```javascript
+    // Check data.access_token format
+    const cred = db.Credential.findOne({ externalId: 'google-user-123' });
+    print('access_token:', cred.data.access_token);
+
+    // Expected format: "keyId:iv:cipher:encKey"
+    // Example: "aes-key-1:1234567890abcdef:a1b2c3d4e5f6...:9876543210fedcba"
+
+    // MUST NOT be plain text like "ya29.a0AfH6SMCX..."
+    ```
+
+-   [ ] Verify encrypted format:
+    ```javascript
+    // Should have 4+ colon-separated parts
+    const parts = cred.data.access_token.split(':');
+    print('Parts count:', parts.length); // Should be >= 4
+    ```
+
+**Manual Test: API Usage**
+
+-   [ ] Use credential through API:
+
+    ```bash
+    # Make API request that uses the credential
+    # Example: Fetch Asana user info
+    curl -X GET http://localhost:3000/api/asana/me \
+      -H "Authorization: Bearer $TOKEN"
+    ```
+
+-   [ ] Verify API call succeeds (credential was decrypted correctly)
+
+**Manual Test: Stage Bypass**
+
+-   [ ] Stop backend
+
+-   [ ] Change to dev stage:
+
+    ```bash
+    export STAGE=dev
+    unset AES_KEY_ID
+    unset AES_KEY
+    ```
+
+-   [ ] Start backend
+
+-   [ ] Create credential
+
+-   [ ] Verify credential stored as plain text (bypass worked):
+    ```javascript
+    // In mongosh:
+    const devCred = db.Credential.findOne({ userId: ObjectId('...') });
+    print('access_token:', devCred.data.access_token);
+    // Should be plain text (not encrypted) in dev stage
+    ```
+
+---
+
+#### 7.3 Integration Testing
+
+**OAuth Flow Testing**:
+
+-   [ ] **Asana OAuth Flow**:
+
+    -   [ ] Start OAuth flow via Asana integration
+    -   [ ] Complete OAuth authorization
+    -   [ ] Verify credential created in database
+    -   [ ] Check credential is encrypted in database
+    -   [ ] Verify Asana API calls work (credential decrypted)
+
+-   [ ] **Frontify OAuth Flow**:
+    -   [ ] Start OAuth flow via Frontify integration
+    -   [ ] Complete OAuth authorization
+    -   [ ] Verify credential created in database
+    -   [ ] Check credential is encrypted in database
+    -   [ ] Verify Frontify API calls work
+
+**Credential Refresh Testing**:
+
+-   [ ] Trigger token refresh (if implemented)
+-   [ ] Verify new tokens are encrypted
+-   [ ] Verify old tokens are overwritten (not duplicated)
+-   [ ] Verify refresh token itself is encrypted
+
+**Multi-User Testing**:
+
+-   [ ] Create credentials for 3 different users
+-   [ ] Verify each credential is independently encrypted
+-   [ ] Verify users can only access their own credentials
+-   [ ] Check for no credential leakage between users
+
+---
+
+#### 7.4 Performance Testing
+
+**Encryption Performance**:
+
+-   [ ] Measure encryption time for single credential:
+
+    ```javascript
+    const start = Date.now();
+    const encrypted = await service.encryptFields('Credential', credential);
+    const encryptTime = Date.now() - start;
+    console.log(`Encryption time: ${encryptTime}ms`);
+    // Should be < 50ms for KMS, < 10ms for AES
+    ```
+
+-   [ ] Measure decryption time for single credential
+
+**Bulk Operations**:
+
+-   [ ] Test bulk credential retrieval (10 credentials):
+
+    ```javascript
+    const start = Date.now();
+    const entities = await moduleRepo.findEntitiesByUserId(userId);
+    const bulkTime = Date.now() - start;
+    console.log(`Bulk retrieval time: ${bulkTime}ms`);
+    // Should be reasonable (< 500ms for 10 credentials)
+    ```
+
+-   [ ] Verify parallel decryption is used (not sequential)
+
+---
+
+#### 7.5 Security Validation
+
+**Encryption Format Verification**:
+
+-   [ ] Create credential with known value
+-   [ ] Query database directly
+-   [ ] Verify format matches: `keyId:iv:cipher:encKey`
+-   [ ] Verify at least 4 colon-separated parts
+-   [ ] Verify base64-like characters in each part
+
+**Decryption Verification**:
+
+-   [ ] Create credential with known value
+-   [ ] Retrieve via repository
+-   [ ] Verify decrypted value matches original
+-   [ ] Verify no corruption or truncation
+
+**Negative Tests**:
+
+-   [ ] Manually corrupt encrypted value in database
+-   [ ] Attempt to retrieve credential
+-   [ ] Verify graceful handling (field set to null, logged error)
+-   [ ] Verify application doesn't crash
+
+**Key Rotation Simulation** (if time permits):
+
+-   [ ] Create credential with key1
+-   [ ] Rotate to key2 (change AES_KEY_ID)
+-   [ ] Verify old credentials still decrypt (backward compatible)
+-   [ ] Verify new credentials use key2
+
+**Estimated Time**: 1.5 hours
+
+---
+
+### Phase 8: Documentation Updates
+
+#### 8.1 Update Main Encryption README
+
+**File**: `packages/core/database/encryption/README.md`
+
+**Sections to Add**:
+
+-   [ ] **Add "DocumentDB Encryption" section** (after "How It Works"):
+
+    ```markdown
+    ## 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)
+
+    #### Implementation Details
+
+    See: [documentdb-encryption-service.md](./documentdb-encryption-service.md)
+    ```
+
+-   [ ] **Update "Adding Encrypted Fields" section**:
+
+    ```markdown
+    After adding fields to `encryption-schema-registry.js`:
+
+    1. **For MongoDB/PostgreSQL**: No code changes needed (automatic)
+    2. **For DocumentDB**: Encryption is automatic via DocumentDBEncryptionService
+       (service reads from same registry)
+    ```
+
+---
+
+#### 8.2 Repository JSDoc Comments
+
+**UserRepositoryDocumentDB**:
+
+-   [ ] Add class-level JSDoc:
+    ```javascript
+    /**
+     * User repository for DocumentDB.
+     * Uses DocumentDBEncryptionService for field-level encryption.
+     *
+     * Encrypted fields: User.hashword
+     *
+     * @see DocumentDBEncryptionService
+     * @see encryption-schema-registry.js
+     */
+    class UserRepositoryDocumentDB extends UserRepositoryInterface {
+    ```
+
+**ModuleRepositoryDocumentDB**:
+
+-   [ ] Add class-level JSDoc:
+    ```javascript
+    /**
+     * Module/Entity repository for DocumentDB.
+     * Uses DocumentDBEncryptionService for credential decryption.
+     *
+     * Encrypted fields: Credential.data.*
+     *
+     * Note: This repository only reads credentials. CredentialRepository
+     * handles credential creation/updates with encryption.
+     *
+     * @see DocumentDBEncryptionService
+     * @see CredentialRepositoryDocumentDB
+     */
+    class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
+    ```
+
+**CredentialRepositoryDocumentDB**:
+
+-   [ ] Add class-level JSDoc:
+    ```javascript
+    /**
+     * 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 {
+    ```
+
+**Estimated Time**: 30 minutes
+
+---
+
+## Total Implementation Time Estimate
+
+| Phase     | Description                                | Time          |
+| --------- | ------------------------------------------ | ------------- |
+| Phase 1   | Create DocumentDBEncryptionService + tests | 2-3 hours     |
+| Phase 2   | Refactor UserRepositoryDocumentDB          | 1 hour        |
+| Phase 3   | Refactor ModuleRepositoryDocumentDB        | 1 hour        |
+| Phase 4   | Fix CredentialRepositoryDocumentDB         | 1.5 hours     |
+| Phase 5   | Add comprehensive tests (3 repos)          | 5 hours       |
+| Phase 6   | Apply to both locations                    | 30 minutes    |
+| Phase 7   | Validation and integration testing         | 1.5 hours     |
+| Phase 8   | Documentation updates                      | 30 minutes    |
+| **Total** |                                            | **~13 hours** |
+
+---
+
+## Code Examples
+
+### Example 1: Before & After - CredentialRepositoryDocumentDB
+
+**BEFORE (Vulnerable - Plain Text Storage)**:
+
+```javascript
+class CredentialRepositoryDocumentDB {
+    constructor() {
+        this.prisma = prisma;
+        // ❌ No encryption service
+    }
+
+    async upsertCredential(credentialDetails) {
+        const { identifiers, details } = credentialDetails;
+        const { user, userId, authIsValid, externalId, ...oauthData } =
+            details || {};
+
+        // ❌ oauthData contains PLAIN TEXT tokens
+        const document = {
+            userId: toObjectId(userId || user),
+            externalId,
+            data: oauthData, // ❌ { access_token: "plain_secret", ... }
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+
+        // ❌ STORED AS PLAIN TEXT
+        const insertedId = await insertOne(this.prisma, 'Credential', document);
+
+        const created = await findOne(this.prisma, 'Credential', {
+            _id: insertedId,
+        });
+        // ❌ Returns encrypted string (if previously encrypted) or plain text
+        return this._mapCredential(created);
+    }
+}
+```
+
+**AFTER (Secure - Encrypted Storage)**:
+
+```javascript
+const {
+    DocumentDBEncryptionService,
+} = require('../database/documentdb-encryption-service');
+
+class CredentialRepositoryDocumentDB {
+    constructor() {
+        this.prisma = prisma;
+        // ✅ Initialize encryption service
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    async upsertCredential(credentialDetails) {
+        const { identifiers, details } = credentialDetails;
+        const { user, userId, authIsValid, externalId, ...oauthData } =
+            details || {};
+
+        // Build plain text document
+        const plainDocument = {
+            userId: toObjectId(userId || user),
+            externalId,
+            data: oauthData, // Still plain text: { access_token: "plain_secret", ... }
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+
+        // ✅ ENCRYPT before storing
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'Credential',
+            plainDocument
+        );
+        // encryptedDocument.data = { access_token: "keyId:iv:cipher:encKey", ... }
+
+        // ✅ STORED AS ENCRYPTED
+        const insertedId = await insertOne(
+            this.prisma,
+            'Credential',
+            encryptedDocument
+        );
+
+        const created = await findOne(this.prisma, 'Credential', {
+            _id: insertedId,
+        });
+
+        // ✅ DECRYPT before returning
+        const decryptedCredential = await this.encryptionService.decryptFields(
+            'Credential',
+            created
+        );
+        // decryptedCredential.data = { access_token: "plain_secret", ... }
+
+        return this._mapCredential(decryptedCredential);
+    }
+}
+```
+
+---
+
+### Example 2: DocumentDBEncryptionService Usage Patterns
+
+**Pattern 1: Single Field Encryption (User.hashword)**:
+
+```javascript
+class UserRepositoryDocumentDB {
+    async createIndividualUser(params) {
+        const document = {
+            type: 'INDIVIDUAL',
+            username: params.username,
+            hashword: await bcrypt.hash(params.hashword, 10), // Bcrypt hash
+            createdAt: new Date(),
+        };
+
+        // Encrypt bcrypt hash before storage
+        const encrypted = await this.encryptionService.encryptFields(
+            'User',
+            document
+        );
+        // encrypted.hashword = "keyId:iv:cipher:encKey"
+
+        const id = await insertOne(this.prisma, 'User', encrypted);
+        const created = await findOne(this.prisma, 'User', { _id: id });
+
+        // Decrypt before returning
+        const decrypted = await this.encryptionService.decryptFields(
+            'User',
+            created
+        );
+        // decrypted.hashword = "$2b$10$..." (bcrypt hash)
+
+        return this._mapUser(decrypted);
+    }
+}
+```
+
+**Pattern 2: Nested Fields Encryption (Credential.data.\*)**:
+
+```javascript
+class CredentialRepositoryDocumentDB {
+    async upsertCredential(details) {
+        const document = {
+            data: {
+                access_token: 'ya29.actual_token',
+                refresh_token: '1//0refresh',
+                id_token: 'eyJhbGci...',
+                expires_at: 1234567890, // Not encrypted (not in registry)
+                scope: 'openid profile', // Not encrypted
+            },
+        };
+
+        // Encrypts only fields defined in encryption-schema-registry.js
+        const encrypted = await this.encryptionService.encryptFields(
+            'Credential',
+            document
+        );
+        // encrypted.data = {
+        //     access_token: "keyId:iv:cipher:encKey",   ← ENCRYPTED
+        //     refresh_token: "keyId:iv:cipher:encKey",  ← ENCRYPTED
+        //     id_token: "keyId:iv:cipher:encKey",       ← ENCRYPTED
+        //     expires_at: 1234567890,                   ← PLAIN (not in registry)
+        //     scope: "openid profile"                   ← PLAIN (not in registry)
+        // }
+    }
+}
+```
+
+**Pattern 3: Bulk Decryption (Multiple Credentials)**:
+
+```javascript
+class ModuleRepositoryDocumentDB {
+    async _fetchCredentialsBulk(credentialIds) {
+        const objectIds = credentialIds
+            .map((id) => toObjectId(id))
+            .filter(Boolean);
+
+        // Fetch all credentials (encrypted)
+        const rawCredentials = await findMany(this.prisma, 'Credential', {
+            _id: { $in: objectIds },
+        });
+
+        // Decrypt in parallel
+        const decryptionPromises = rawCredentials.map(async (rawCredential) => {
+            const decrypted = await this.encryptionService.decryptFields(
+                'Credential',
+                rawCredential
+            );
+            return this._mapCredential(decrypted);
+        });
+
+        return await Promise.all(decryptionPromises);
+    }
+}
+```
+
+---
+
+### Example 3: Complete Flow - OAuth Credential Creation
+
+```javascript
+// 1. User completes OAuth flow, application receives tokens
+const oauthTokens = {
+    access_token: 'ya29.a0AfH6SMCXyz...',
+    refresh_token: '1//0gFz6TRvwUm...',
+    id_token: 'eyJhbGciOiJSUzI1...',
+    expires_in: 3600,
+    token_type: 'Bearer',
+};
+
+// 2. Use case calls repository
+const credential = await credentialRepository.upsertCredential({
+    identifiers: { userId: 'user123', externalId: 'google-user-456' },
+    details: oauthTokens,
+});
+
+// 3. Inside repository: Build plain document
+const plainDocument = {
+    userId: toObjectId('user123'),
+    externalId: 'google-user-456',
+    data: {
+        access_token: 'ya29.a0AfH6SMCXyz...',
+        refresh_token: '1//0gFz6TRvwUm...',
+        id_token: 'eyJhbGciOiJSUzI1...',
+        expires_in: 3600,
+        token_type: 'Bearer',
+    },
+};
+
+// 4. DocumentDBEncryptionService encrypts sensitive fields
+const encryptedDocument = await this.encryptionService.encryptFields(
+    'Credential',
+    plainDocument
+);
+// Result:
+// {
+//     userId: ObjectId("..."),
+//     externalId: "google-user-456",
+//     data: {
+//         access_token: "aes-key-1:a1b2c3:d4e5f6:g7h8i9",       ← ENCRYPTED
+//         refresh_token: "aes-key-1:j1k2l3:m4n5o6:p7q8r9",      ← ENCRYPTED
+//         id_token: "aes-key-1:s1t2u3:v4w5x6:y7z8a9",           ← ENCRYPTED
+//         expires_in: 3600,                                       ← PLAIN (not in registry)
+//         token_type: "Bearer"                                    ← PLAIN (not in registry)
+//     }
+// }
+
+// 5. Store in DocumentDB
+await insertOne(this.prisma, 'Credential', encryptedDocument);
+
+// 6. Read back from DocumentDB
+const rawDocument = await findOne(this.prisma, 'Credential', {
+    userId: objectId,
+});
+// Returns encrypted data as stored
+
+// 7. DocumentDBEncryptionService decrypts sensitive fields
+const decryptedDocument = await this.encryptionService.decryptFields(
+    'Credential',
+    rawDocument
+);
+// Result:
+// {
+//     data: {
+//         access_token: "ya29.a0AfH6SMCXyz...",      ← DECRYPTED
+//         refresh_token: "1//0gFz6TRvwUm...",         ← DECRYPTED
+//         id_token: "eyJhbGciOiJSUzI1...",            ← DECRYPTED
+//         expires_in: 3600,
+//         token_type: "Bearer"
+//     }
+// }
+
+// 8. Use case receives plain text credential
+return credential; // { access_token: "ya29...", refresh_token: "1//0...", ... }
+
+// 9. Application makes API call
+await fetch('https://www.googleapis.com/oauth2/v1/userinfo', {
+    headers: { Authorization: `Bearer ${credential.access_token}` },
+});
+// ✅ Works! Token is usable
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests: DocumentDBEncryptionService
+
+**Coverage Goals**:
+
+-   100% line coverage
+-   All branches covered
+-   All error paths tested
+
+**Key Test Cases**:
+
+```javascript
+describe('DocumentDBEncryptionService', () => {
+    describe('Initialization', () => {
+        it('bypasses encryption in dev stage', () => {
+            process.env.STAGE = 'dev';
+            const service = new DocumentDBEncryptionService();
+            expect(service.enabled).toBe(false);
+            expect(service.cryptor).toBeNull();
+        });
+
+        it('enables KMS encryption in production with KMS_KEY_ARN', () => {
+            process.env.STAGE = 'production';
+            process.env.KMS_KEY_ARN =
+                'arn:aws:kms:us-east-1:123456789012:key/abc123';
+            const service = new DocumentDBEncryptionService();
+            expect(service.enabled).toBe(true);
+            expect(service.cryptor.shouldUseAws).toBe(true);
+        });
+
+        it('enables AES encryption in production with AES_KEY_ID', () => {
+            process.env.STAGE = 'production';
+            process.env.AES_KEY_ID = 'local-key';
+            process.env.AES_KEY = '01234567890123456789012345678901';
+            const service = new DocumentDBEncryptionService();
+            expect(service.enabled).toBe(true);
+            expect(service.cryptor.shouldUseAws).toBe(false);
+        });
+    });
+
+    describe('encryptFields()', () => {
+        it('encrypts User.hashword', async () => {
+            const document = {
+                username: 'test@example.com',
+                hashword: '$2b$10$plain_bcrypt_hash',
+            };
+
+            const encrypted = await service.encryptFields('User', document);
+
+            expect(encrypted.username).toBe('test@example.com'); // Not encrypted
+            expect(encrypted.hashword).not.toBe('$2b$10$plain_bcrypt_hash'); // Encrypted
+            expect(encrypted.hashword).toMatch(/^[^:]+:[^:]+:[^:]+:[^:]+$/); // Format check
+        });
+
+        it('encrypts Credential.data.access_token', async () => {
+            const document = {
+                userId: '123',
+                data: {
+                    access_token: 'ya29.token_here',
+                    scope: 'openid profile', // Not in registry
+                },
+            };
+
+            const encrypted = await service.encryptFields(
+                'Credential',
+                document
+            );
+
+            expect(encrypted.data.access_token).not.toBe('ya29.token_here');
+            expect(encrypted.data.access_token).toMatch(
+                /^[^:]+:[^:]+:[^:]+:[^:]+$/
+            );
+            expect(encrypted.data.scope).toBe('openid profile'); // Not encrypted
+        });
+
+        it('skips already encrypted values', async () => {
+            const alreadyEncrypted = 'keyId:iv123:cipher456:enckey789';
+            const document = { hashword: alreadyEncrypted };
+
+            const result = await service.encryptFields('User', document);
+
+            expect(result.hashword).toBe(alreadyEncrypted); // Unchanged
+        });
+
+        it('returns unchanged for unknown model', async () => {
+            const document = { field: 'value' };
+            const result = await service.encryptFields(
+                'UnknownModel',
+                document
+            );
+            expect(result).toEqual(document);
+        });
+    });
+
+    describe('decryptFields()', () => {
+        it('decrypts User.hashword', async () => {
+            const encryptedDoc = {
+                username: 'test@example.com',
+                hashword: 'keyId:iv:cipher:enckey', // Mock encrypted
+            };
+
+            // Mock Cryptor to return known value
+            mockCryptor.decrypt.mockResolvedValue('$2b$10$plain_bcrypt_hash');
+
+            const decrypted = await service.decryptFields('User', encryptedDoc);
+
+            expect(decrypted.hashword).toBe('$2b$10$plain_bcrypt_hash');
+            expect(mockCryptor.decrypt).toHaveBeenCalledWith(
+                'keyId:iv:cipher:enckey'
+            );
+        });
+
+        it('handles decryption failures gracefully', async () => {
+            const encryptedDoc = { hashword: 'corrupted:data:here:error' };
+            mockCryptor.decrypt.mockRejectedValue(
+                new Error('Decryption failed')
+            );
+
+            const result = await service.decryptFields('User', encryptedDoc);
+
+            expect(result.hashword).toBeNull(); // Set to null on error
+        });
+
+        it('parses JSON objects after decryption', async () => {
+            const encryptedDoc = { data: { config: 'keyId:iv:cipher:enckey' } };
+            const jsonObject = { nested: 'value', array: [1, 2, 3] };
+            mockCryptor.decrypt.mockResolvedValue(JSON.stringify(jsonObject));
+
+            const result = await service.decryptFields(
+                'CustomModel',
+                encryptedDoc
+            );
+
+            expect(result.data.config).toEqual(jsonObject); // Parsed as object
+        });
+    });
+});
+```
+
+---
+
+### Integration Tests: Repository Level
+
+**CredentialRepositoryDocumentDB Security Tests**:
+
+```javascript
+describe('CredentialRepositoryDocumentDB - Security', () => {
+    let repository;
+    let prisma;
+
+    beforeAll(async () => {
+        // Setup DocumentDB test database
+        process.env.STAGE = 'production';
+        process.env.AES_KEY_ID = 'test-key';
+        process.env.AES_KEY = '01234567890123456789012345678901';
+
+        prisma = await connectPrisma();
+        repository = new CredentialRepositoryDocumentDB({ prisma });
+    });
+
+    afterAll(async () => {
+        await disconnectPrisma();
+    });
+
+    describe('CRITICAL: OAuth Token Encryption', () => {
+        it('stores access_token encrypted in database', async () => {
+            const userId = new ObjectId();
+            const externalId = 'google-user-123';
+            const plainToken = 'ya29.actual_google_token_here';
+
+            // Create credential via repository
+            await repository.upsertCredential({
+                identifiers: { userId: fromObjectId(userId), externalId },
+                details: { access_token: plainToken, token_type: 'Bearer' },
+            });
+
+            // Query database directly (bypass repository)
+            const rawResult = await prisma.$runCommandRaw({
+                find: 'Credential',
+                filter: { userId, externalId },
+            });
+
+            const storedCredential = rawResult.cursor.firstBatch[0];
+            const storedToken = storedCredential.data.access_token;
+
+            // CRITICAL ASSERTIONS
+            expect(storedToken).not.toBe(plainToken); // NOT plain text
+            expect(storedToken).toMatch(/^[^:]+:[^:]+:[^:]+:[^:]+$/); // Encrypted format
+            expect(storedToken.split(':').length).toBeGreaterThanOrEqual(4); // 4+ parts
+
+            // Verify repository returns decrypted
+            const retrieved = await repository.findCredential({
+                userId: fromObjectId(userId),
+                externalId,
+            });
+            expect(retrieved.access_token).toBe(plainToken); // Decrypted
+        });
+
+        it('encrypts refresh_token', async () => {
+            const userId = new ObjectId();
+            const plainRefresh = '1//0secret_refresh_token';
+
+            await repository.upsertCredential({
+                identifiers: {
+                    userId: fromObjectId(userId),
+                    externalId: 'test-456',
+                },
+                details: { refresh_token: plainRefresh },
+            });
+
+            const rawResult = await prisma.$runCommandRaw({
+                find: 'Credential',
+                filter: { userId },
+            });
+
+            const stored = rawResult.cursor.firstBatch[0].data.refresh_token;
+            expect(stored).not.toBe(plainRefresh);
+            expect(stored).toMatch(/^[^:]+:[^:]+:[^:]+:[^:]+$/);
+        });
+
+        it('encrypts id_token', async () => {
+            const userId = new ObjectId();
+            const plainIdToken = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
+
+            await repository.upsertCredential({
+                identifiers: {
+                    userId: fromObjectId(userId),
+                    externalId: 'test-789',
+                },
+                details: { id_token: plainIdToken },
+            });
+
+            const rawResult = await prisma.$runCommandRaw({
+                find: 'Credential',
+                filter: { userId },
+            });
+
+            const stored = rawResult.cursor.firstBatch[0].data.id_token;
+            expect(stored).not.toBe(plainIdToken);
+            expect(stored).toMatch(/^[^:]+:[^:]+:[^:]+:[^:]+$/);
+        });
+
+        it('does NOT encrypt non-sensitive fields', async () => {
+            const userId = new ObjectId();
+
+            await repository.upsertCredential({
+                identifiers: {
+                    userId: fromObjectId(userId),
+                    externalId: 'test-000',
+                },
+                details: {
+                    access_token: 'token123',
+                    expires_in: 3600, // Not in encrypted fields registry
+                    token_type: 'Bearer', // Not in registry
+                    scope: 'openid profile', // Not in registry
+                },
+            });
+
+            const rawResult = await prisma.$runCommandRaw({
+                find: 'Credential',
+                filter: { userId },
+            });
+
+            const stored = rawResult.cursor.firstBatch[0].data;
+
+            // These should NOT be encrypted
+            expect(stored.expires_in).toBe(3600);
+            expect(stored.token_type).toBe('Bearer');
+            expect(stored.scope).toBe('openid profile');
+
+            // But access_token should be encrypted
+            expect(stored.access_token).toMatch(/^[^:]+:[^:]+:[^:]+:[^:]+$/);
+        });
+    });
+
+    describe('Full Integration Flow', () => {
+        it('encrypts on insert, decrypts on read', async () => {
+            const userId = new ObjectId();
+            const plainData = {
+                access_token: 'test_access_123',
+                refresh_token: 'test_refresh_456',
+                expires_in: 7200,
+            };
+
+            // Insert
+            const created = await repository.upsertCredential({
+                identifiers: {
+                    userId: fromObjectId(userId),
+                    externalId: 'flow-test',
+                },
+                details: plainData,
+            });
+
+            // Verify returned data is plain text
+            expect(created.access_token).toBe('test_access_123');
+            expect(created.refresh_token).toBe('test_refresh_456');
+
+            // Read via repository
+            const retrieved = await repository.findCredential({
+                userId: fromObjectId(userId),
+                externalId: 'flow-test',
+            });
+
+            // Verify decrypted correctly
+            expect(retrieved.access_token).toBe('test_access_123');
+            expect(retrieved.refresh_token).toBe('test_refresh_456');
+
+            // Verify database has encrypted values
+            const rawResult = await prisma.$runCommandRaw({
+                find: 'Credential',
+                filter: { userId },
+            });
+            const stored = rawResult.cursor.firstBatch[0].data;
+            expect(stored.access_token).not.toBe('test_access_123');
+            expect(stored.refresh_token).not.toBe('test_refresh_456');
+        });
+    });
+
+    describe('Stage-Based Bypass', () => {
+        it('bypasses encryption in dev stage', async () => {
+            // Re-initialize with dev stage
+            process.env.STAGE = 'dev';
+            const devRepo = new CredentialRepositoryDocumentDB({ prisma });
+
+            const userId = new ObjectId();
+            const plainToken = 'dev_token_plain';
+
+            await devRepo.upsertCredential({
+                identifiers: {
+                    userId: fromObjectId(userId),
+                    externalId: 'dev-test',
+                },
+                details: { access_token: plainToken },
+            });
+
+            // In dev, should be stored as plain text
+            const rawResult = await prisma.$runCommandRaw({
+                find: 'Credential',
+                filter: { userId },
+            });
+            const stored = rawResult.cursor.firstBatch[0].data.access_token;
+            expect(stored).toBe(plainToken); // Plain text in dev!
+
+            // Reset to production
+            process.env.STAGE = 'production';
+        });
+    });
+});
+```
+
+---
+
+### Manual Test Script
+
+```bash
+#!/bin/bash
+# manual-encryption-test.sh
+# Tests DocumentDB encryption manually
+
+set -e
+
+echo "🔐 DocumentDB Encryption Manual Test"
+echo "===================================="
+
+# Setup
+export STAGE=production
+export AES_KEY_ID=test-manual-key
+export AES_KEY=01234567890123456789012345678901
+
+echo "✅ Environment configured (production, AES encryption)"
+
+# Start MongoDB
+echo "📦 Starting MongoDB..."
+docker-compose up -d mongo
+sleep 5
+
+# Start backend
+echo "🚀 Starting backend..."
+cd backend
+npm run frigg:start &
+BACKEND_PID=$!
+sleep 10
+
+# Create user
+echo "👤 Creating test user..."
+TOKEN=$(curl -s -X POST http://localhost:3000/user/create \
+    -H "Content-Type: application/json" \
+    -d '{"username":"test@encryption.com","password":"testpass"}' \
+    | jq -r '.token')
+
+echo "✅ User created, token: ${TOKEN:0:20}..."
+
+# Trigger OAuth flow (simulated)
+echo "🔑 Simulating OAuth credential creation..."
+# Note: This would normally be done through OAuth flow
+# For testing, we can directly call credential creation endpoint if it exists
+
+# Verify encryption in database
+echo "🔍 Verifying encryption in database..."
+docker exec -it $(docker ps -q -f name=mongo) mongosh --eval "
+use frigg;
+var cred = db.Credential.findOne();
+if (cred) {
+    print('Found credential:');
+    print('  ID: ' + cred._id);
+    print('  access_token format: ' + cred.data.access_token);
+
+    var parts = cred.data.access_token.split(':');
+    if (parts.length >= 4) {
+        print('  ✅ ENCRYPTED (4+ parts)');
+    } else {
+        print('  ❌ NOT ENCRYPTED (plain text)');
+        quit(1);
+    }
+} else {
+    print('⚠️  No credentials found');
+}
+"
+
+echo "✅ Manual test complete"
+
+# Cleanup
+kill $BACKEND_PID
+docker-compose down
+```
+
+---
+
+## Migration Guide
+
+### For Existing Deployments with Plain Text Credentials
+
+**⚠️ WARNING**: If DocumentDB repositories are already deployed and storing plain text credentials, follow this migration plan.
+
+---
+
+### Step 1: Assess the Damage
+
+**Query Database for Plain Text Credentials**:
+
+```javascript
+// Run in mongosh on DocumentDB
+
+use frigg;
+
+// Check total credentials
+var totalCreds = db.Credential.countDocuments();
+print('Total credentials:', totalCreds);
+
+// Sample credentials to check format
+var sampleCreds = db.Credential.find().limit(10).toArray();
+
+sampleCreds.forEach(function(cred) {
+    var token = cred.data?.access_token;
+    if (!token) {
+        print('Credential', cred._id, ': No access_token');
+        return;
+    }
+
+    var parts = token.split(':');
+    if (parts.length >= 4) {
+        print('Credential', cred._id, ': ENCRYPTED ✅');
+    } else {
+        print('Credential', cred._id, ': PLAIN TEXT ❌', token.substring(0, 20) + '...');
+    }
+});
+```
+
+**Estimate Impact**:
+
+-   Number of affected credentials
+-   Number of affected users
+-   Third-party services (Asana, Frontify, etc.)
+
+---
+
+### Step 2: Immediate Security Response
+
+**Priority Actions**:
+
+1. **Deploy Fix Immediately**:
+
+    ```bash
+    # Deploy encryption fix to stop new plain text storage
+    cd backend
+    npm install @friggframework/core@latest  # With encryption fix
+    npm run deploy -- --stage production
+    ```
+
+2. **Rotate All Affected Tokens**:
+
+    - Force OAuth re-authentication for all users
+    - Revoke old tokens on third-party services
+    - Generate new encrypted tokens
+
+3. **Audit Access**:
+    - Review database access logs
+    - Identify who had access to plain text credentials
+    - Check for unauthorized API usage
+
+---
+
+### Step 3: Data Migration
+
+**Migration Script** (`migrate-encrypt-credentials.js`):
+
+```javascript
+const {
+    prisma,
+    connectPrisma,
+    disconnectPrisma,
+} = require('@friggframework/core/database/prisma');
+const {
+    DocumentDBEncryptionService,
+} = require('@friggframework/core/database/documentdb-encryption-service');
+const {
+    toObjectId,
+    fromObjectId,
+} = require('@friggframework/core/database/documentdb-utils');
+
+/**
+ * Migrate plain text credentials to encrypted format.
+ *
+ * This script:
+ * 1. Identifies plain text credentials
+ * 2. Encrypts them using DocumentDBEncryptionService
+ * 3. Updates database with encrypted values
+ * 4. Verifies encryption
+ */
+async function migrateCredentials() {
+    console.log('🔐 Starting credential encryption migration...');
+
+    // Initialize
+    await connectPrisma();
+    const encryptionService = new DocumentDBEncryptionService();
+
+    if (!encryptionService.enabled) {
+        console.error(
+            '❌ Encryption not enabled! Check environment variables.'
+        );
+        process.exit(1);
+    }
+
+    // Fetch all credentials
+    const result = await prisma.$runCommandRaw({
+        find: 'Credential',
+        filter: {},
+    });
+
+    const credentials = result.cursor.firstBatch;
+    console.log(`📊 Found ${credentials.length} credentials`);
+
+    let encryptedCount = 0;
+    let alreadyEncryptedCount = 0;
+    let errorCount = 0;
+
+    for (const cred of credentials) {
+        const credId = fromObjectId(cred._id);
+
+        try {
+            // Check if already encrypted
+            const token = cred.data?.access_token;
+            if (!token) {
+                console.log(
+                    `⏭️  Skipping credential ${credId} (no access_token)`
+                );
+                continue;
+            }
+
+            const parts = token.split(':');
+            if (parts.length >= 4) {
+                console.log(`✅ Credential ${credId} already encrypted`);
+                alreadyEncryptedCount++;
+                continue;
+            }
+
+            // Encrypt credential data
+            console.log(`🔐 Encrypting credential ${credId}...`);
+            const encryptedData = await encryptionService.encryptFields(
+                'Credential',
+                {
+                    data: cred.data,
+                }
+            );
+
+            // Update database
+            await prisma.$runCommandRaw({
+                update: 'Credential',
+                updates: [
+                    {
+                        q: { _id: cred._id },
+                        u: {
+                            $set: {
+                                data: encryptedData.data,
+                                updatedAt: new Date(),
+                            },
+                        },
+                    },
+                ],
+            });
+
+            console.log(`✅ Encrypted credential ${credId}`);
+            encryptedCount++;
+        } catch (error) {
+            console.error(
+                `❌ Failed to encrypt credential ${credId}:`,
+                error.message
+            );
+            errorCount++;
+        }
+    }
+
+    console.log('\n📊 Migration Summary:');
+    console.log(`  Total credentials: ${credentials.length}`);
+    console.log(`  Encrypted: ${encryptedCount}`);
+    console.log(`  Already encrypted: ${alreadyEncryptedCount}`);
+    console.log(`  Errors: ${errorCount}`);
+
+    await disconnectPrisma();
+    console.log('✅ Migration complete');
+}
+
+// Run migration
+migrateCredentials().catch((error) => {
+    console.error('💥 Migration failed:', error);
+    process.exit(1);
+});
+```
+
+**Run Migration**:
+
+```bash
+# Set production environment variables
+export STAGE=production
+export KMS_KEY_ARN=arn:aws:kms:us-east-1:123456789012:key/abc123
+
+# Run migration
+node migrate-encrypt-credentials.js
+
+# Verify
+node verify-encryption.js  # See verification script below
+```
+
+---
+
+### Step 4: Verification
+
+**Verification Script** (`verify-encryption.js`):
+
+```javascript
+const {
+    prisma,
+    connectPrisma,
+    disconnectPrisma,
+} = require('@friggframework/core/database/prisma');
+
+async function verifyEncryption() {
+    console.log('🔍 Verifying credential encryption...');
+
+    await connectPrisma();
+
+    const result = await prisma.$runCommandRaw({
+        find: 'Credential',
+        filter: {},
+    });
+
+    const credentials = result.cursor.firstBatch;
+    let passCount = 0;
+    let failCount = 0;
+
+    for (const cred of credentials) {
+        const token = cred.data?.access_token;
+        if (!token) continue;
+
+        const parts = token.split(':');
+        if (parts.length >= 4) {
+            passCount++;
+        } else {
+            console.error(`❌ Plain text found in credential ${cred._id}`);
+            failCount++;
+        }
+    }
+
+    await disconnectPrisma();
+
+    console.log('\n📊 Verification Results:');
+    console.log(`  Encrypted: ${passCount}`);
+    console.log(`  Plain text: ${failCount}`);
+
+    if (failCount > 0) {
+        console.error(
+            '\n❌ Verification failed! Plain text credentials still exist.'
+        );
+        process.exit(1);
+    } else {
+        console.log('\n✅ Verification passed! All credentials encrypted.');
+    }
+}
+
+verifyEncryption().catch((error) => {
+    console.error('💥 Verification failed:', error);
+    process.exit(1);
+});
+```
+
+---
+
+### Step 5: Post-Migration Cleanup
+
+1. **Delete Migration Scripts**:
+
+    ```bash
+    rm migrate-encrypt-credentials.js
+    rm verify-encryption.js
+    ```
+
+2. **Update Documentation**:
+
+    - Document the incident
+    - Document lessons learned
+    - Update security procedures
+
+3. **Monitor**:
+    - Set up alerts for plain text detection
+    - Monitor API error rates (in case decryption fails)
+    - Watch for OAuth re-authentication requests
+
+---
+
+### Rollback Procedures
+
+**If Migration Fails**:
+
+1. **Stop the migration script**
+
+2. **Restore from backup**:
+
+    ```bash
+    # Restore MongoDB backup from before migration
+    mongorestore --uri="mongodb://..." --archive=backup-before-migration.archive
+    ```
+
+3. **Revert code deployment**:
+
+    ```bash
+    # Rollback to previous version
+    cd backend
+    npm install @friggframework/core@<previous-version>
+    npm run deploy -- --stage production
+    ```
+
+4. **Investigate and fix issues**
+
+5. **Re-attempt migration with fixes**
+
+---
+
+### Zero-Downtime Migration Strategy
+
+For large deployments:
+
+1. **Phase 1: Deploy encryption fix** (don't migrate yet)
+
+    - New credentials will be encrypted
+    - Old credentials remain as-is
+    - Application handles both encrypted and plain text
+
+2. **Phase 2: Migrate in batches**
+
+    ```javascript
+    // Migrate 100 credentials at a time
+    const batchSize = 100;
+    for (let skip = 0; skip < totalCredentials; skip += batchSize) {
+        await migrateBatch(skip, batchSize);
+        await sleep(1000); // 1 second between batches
+    }
+    ```
+
+3. **Phase 3: Verify**
+
+    - Check random samples
+    - Monitor error rates
+    - Verify API calls still work
+
+4. **Phase 4: Complete**
+    - Remove backward compatibility code
+    - Update monitoring alerts
+
+---
+
+## Security Considerations
+
+### Encryption Format
+
+**Envelope Encryption Pattern**:
+
+```
+keyId:iv:cipher:encKey
+```
+
+**Components**:
+
+-   `keyId`: Identifier for the encryption key (e.g., "aes-key-1", KMS key ID)
+-   `iv`: Initialization vector (base64-encoded)
+-   `cipher`: Encrypted data (base64-encoded)
+-   `encKey`: Encrypted data encryption key (base64-encoded)
+
+**Example**:
+
+```
+aes-key-1:MTIzNDU2Nzg5MGFiY2RlZg==:ZW5jcnlwdGVkX2RhdGFfaGVyZQ==:ZGVrX2VuY3J5cHRlZA==
+```
+
+---
+
+### Key Management
+
+**Production (KMS - Recommended)**:
+
+```bash
+# AWS KMS key is auto-discovered by Frigg infrastructure
+# Or set explicitly:
+export KMS_KEY_ARN=arn:aws:kms:us-east-1:123456789012:key/abc-123-def-456
+
+# Stage must be production
+export STAGE=production
+```
+
+**Benefits**:
+
+-   ✅ AWS-managed key rotation
+-   ✅ Audit trail via CloudTrail
+-   ✅ Fine-grained IAM permissions
+-   ✅ Hardware security module (HSM) backed
+-   ✅ Compliance-ready (HIPAA, PCI-DSS, etc.)
+
+**Alternative (AES - Any Environment)**:
+
+```bash
+# Generate a 32-character key
+export AES_KEY_ID=my-app-key-v1
+export AES_KEY=$(openssl rand -hex 16)  # 32 hex chars = 16 bytes
+
+# Can be used in production
+export STAGE=production
+```
+
+**Benefits**:
+
+-   ✅ Works in any environment (no AWS required)
+-   ✅ Faster than KMS (no network calls)
+-   ✅ No AWS costs
+
+**Drawbacks**:
+
+-   ⚠️ Must securely manage key yourself
+-   ⚠️ No automatic key rotation
+-   ⚠️ Key stored in environment/config
+
+---
+
+### Stage-Based Bypass
+
+**Purpose**: Skip encryption in local development for easier debugging
+
+**Bypassed Stages**:
+
+-   `dev`
+-   `test`
+-   `local`
+
+**Production Stages** (encryption enabled):
+
+-   `production`
+-   `prod`
+-   `staging`
+-   `stage`
+-   Any other value
+
+**Configuration**:
+
+```bash
+# Bypass encryption (dev)
+export STAGE=dev
+# DocumentDBEncryptionService.enabled = false
+# Data stored as plain text
+
+# Enable encryption (production)
+export STAGE=production
+export KMS_KEY_ARN=...
+# DocumentDBEncryptionService.enabled = true
+# Data stored encrypted
+```
+
+**Security Note**: Never use `STAGE=dev` in production environments!
+
+---
+
+### Encrypted Fields Registry
+
+**Location**: `packages/core/database/encryption/encryption-schema-registry.js`
+
+**Current Encrypted Fields**:
+
+```javascript
+const ENCRYPTED_FIELDS = {
+    User: ['hashword'],
+    Credential: [
+        'data.access_token',
+        'data.refresh_token',
+        'data.id_token',
+        'data.domain',
+    ],
+    IntegrationMapping: ['mapping'],
+    Token: ['token'],
+};
+```
+
+**Adding New Encrypted Fields**:
+
+1. Open `encryption-schema-registry.js`
+2. Add field path to appropriate model:
+    ```javascript
+    Credential: [
+        'data.access_token',
+        'data.refresh_token',
+        'data.id_token',
+        'data.domain',
+        'data.client_secret', // ← NEW
+    ];
+    ```
+3. Deploy - encryption applied automatically (no code changes needed)
+
+**Field Path Examples**:
+
+-   Top-level: `hashword` → encrypts `document.hashword`
+-   Nested: `data.access_token` → encrypts `document.data.access_token`
+-   Deep nesting supported: `config.secrets.apiKey`
+
+---
+
+### Compliance & Best Practices
+
+**GDPR Compliance**:
+
+-   ✅ Data encrypted at rest
+-   ✅ Encryption keys managed securely
+-   ✅ User data can be deleted (right to erasure)
+
+**PCI-DSS Compliance** (if storing payment data):
+
+-   ✅ Encryption of cardholder data
+-   ✅ Key management procedures
+-   ✅ Audit logging (via CloudTrail with KMS)
+
+**HIPAA Compliance** (if storing health data):
+
+-   ✅ Encryption at rest (required)
+-   ✅ Access controls (AWS KMS IAM)
+-   ✅ Audit trail (CloudTrail)
+
+**Best Practices**:
+
+1. **Use KMS in production** - Better security, compliance, key rotation
+2. **Rotate keys periodically** - Even with KMS, review and rotate annually
+3. **Monitor decryption failures** - Alert on >1% failure rate
+4. **Test encryption in CI/CD** - Automated tests verify encryption works
+5. **Secure key storage** - Never commit keys to version control
+6. **Least privilege access** - Limit who can decrypt data
+
+---
+
+### Security Audit Checklist
+
+Before going to production:
+
+-   [ ] Verify `STAGE=production` in environment
+-   [ ] Verify encryption keys configured (`KMS_KEY_ARN` or `AES_KEY_ID`)
+-   [ ] Run security tests (verify encrypted format in database)
+-   [ ] Test credential creation and retrieval end-to-end
+-   [ ] Verify OAuth flows work (tokens decrypted correctly)
+-   [ ] Check logs for decryption errors
+-   [ ] Review IAM permissions (if using KMS)
+-   [ ] Test key rotation procedure (if using KMS)
+-   [ ] Document encryption architecture for auditors
+-   [ ] Set up monitoring alerts (decryption failures, plain text detection)
+
+---
+
+## Maintenance & Future Work
+
+### Adding New DocumentDB Repositories
+
+When creating a new DocumentDB repository that handles encrypted data:
+
+1. **Import DocumentDBEncryptionService**:
+
+    ```javascript
+    const {
+        DocumentDBEncryptionService,
+    } = require('../database/documentdb-encryption-service');
+    ```
+
+2. **Initialize in constructor**:
+
+    ```javascript
+    constructor() {
+        this.prisma = prisma;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+    ```
+
+3. **Encrypt before writes**:
+
+    ```javascript
+    async create(data) {
+        const encrypted = await this.encryptionService.encryptFields('ModelName', data);
+        const id = await insertOne(this.prisma, 'CollectionName', encrypted);
+        // ...
+    }
+    ```
+
+4. **Decrypt after reads**:
+
+    ```javascript
+    async findById(id) {
+        const doc = await findOne(this.prisma, 'CollectionName', { _id: toObjectId(id) });
+        const decrypted = await this.encryptionService.decryptFields('ModelName', doc);
+        return this._mapModel(decrypted);
+    }
+    ```
+
+5. **Add encrypted fields to registry** (if new model):
+
+    ```javascript
+    // packages/core/database/encryption/encryption-schema-registry.js
+    const ENCRYPTED_FIELDS = {
+        // ... existing models
+        NewModel: ['sensitiveField1', 'nested.field2'],
+    };
+    ```
+
+6. **Add tests** (see Phase 5 for test patterns)
+
+---
+
+### Adding New Encrypted Fields
+
+To encrypt a new field in an existing model:
+
+1. **Update encryption-schema-registry.js**:
+
+    ```javascript
+    const ENCRYPTED_FIELDS = {
+        Credential: [
+            'data.access_token',
+            'data.refresh_token',
+            'data.id_token',
+            'data.domain',
+            'data.client_secret', // ← NEW FIELD
+        ],
+    };
+    ```
+
+2. **No code changes needed** - DocumentDBEncryptionService reads from registry
+
+3. **Deploy** - new field will be encrypted automatically
+
+4. **Migrate existing data** (if field already has plain text values):
+    ```javascript
+    // Run migration script to encrypt existing plain text values
+    // Similar to credential migration script
+    ```
+
+---
+
+### Known Limitations
+
+1. **Performance**: Encryption/decryption adds latency
+
+    - KMS: ~50ms per field (network call to AWS)
+    - AES: ~5-10ms per field (local crypto)
+    - **Mitigation**: Use bulk operations, consider caching decrypted values
+
+2. **DocumentDB-specific**: Only needed for DocumentDB
+
+    - MongoDB/PostgreSQL use automatic Prisma Extension
+    - Duplicate logic unavoidable (Prisma raw queries bypass extensions)
+
+3. **Manual encryption required**: Developers must remember to call service
+
+    - **Mitigation**: Code reviews, tests, linting rules
+
+4. **No transactional encryption**: Encryption happens outside transactions
+
+    - **Risk**: If encryption fails mid-operation, could leave inconsistent state
+    - **Mitigation**: Encrypt before transaction starts, handle errors
+
+5. **Field-level only**: Doesn't encrypt entire documents or collections
+    - **Alternative**: Use database-level encryption (AWS DocumentDB encryption at rest)
+
+---
+
+### Future Improvements
+
+1. **Automatic Repository Decorator**:
+
+    ```javascript
+    // Potential future API
+    @encryptDocumentDB(['User', 'Credential'])
+    class MyRepositoryDocumentDB {
+        // Encryption applied automatically by decorator
+    }
+    ```
+
+2. **Encryption Caching**:
+
+    - Cache decrypted values for frequently accessed credentials
+    - Invalidate cache on credential update
+    - Reduce KMS API calls
+
+3. **Field Compression**:
+
+    - Compress large fields before encryption
+    - Reduce storage and transfer costs
+    - Especially useful for `IntegrationMapping.mapping`
+
+4. **Key Versioning**:
+
+    - Support multiple active keys
+    - Gradual key rotation without migration
+    - Store key version with encrypted data
+
+5. **Encryption Metrics**:
+
+    - Track encryption/decryption performance
+    - Monitor failure rates
+    - Alert on anomalies
+
+6. **Integration with Prisma Extension**:
+    - Potential future Prisma feature: Extension support for raw queries
+    - Would eliminate need for DocumentDBEncryptionService
+    - Track: https://github.com/prisma/prisma/issues/...
+
+---
+
+### Monitoring & Alerts
+
+**Recommended Metrics**:
+
+1. **Encryption Failures**:
+
+    ```javascript
+    // Log when encryption fails
+    console.error('Encryption failed', { modelName, fieldPath, error });
+    // Alert if >1% of operations fail
+    ```
+
+2. **Decryption Failures**:
+
+    ```javascript
+    // Log when decryption fails
+    console.error('Decryption failed', { modelName, fieldPath, error });
+    // Alert immediately (could indicate data corruption)
+    ```
+
+3. **Plain Text Detection**:
+
+    ```javascript
+    // Periodic scan of database
+    // Alert if any plain text credentials found
+    ```
+
+4. **Performance Metrics**:
+    ```javascript
+    // Track encryption/decryption time
+    const start = Date.now();
+    await service.encryptFields(...);
+    const duration = Date.now() - start;
+    metrics.histogram('encryption_duration_ms', duration);
+    ```
+
+**CloudWatch Dashboards** (for AWS deployments):
+
+-   Encryption operation count
+-   Average encryption duration
+-   Decryption failure rate
+-   KMS API call count (if using KMS)
+
+---
+
+### Support & Troubleshooting
+
+**Common Issues**:
+
+1. **"No encryption keys configured"**
+
+    - **Cause**: Missing `KMS_KEY_ARN` or `AES_KEY_ID` in production
+    - **Fix**: Set environment variables, restart application
+
+2. **"Decryption failed"**
+
+    - **Cause**: Wrong key, corrupted data, or key rotation
+    - **Fix**: Check key configuration, verify data integrity, check key version
+
+3. **"Cannot read property 'access_token' of undefined"**
+
+    - **Cause**: Credential data is null or decryption returned null
+    - **Fix**: Check if credential exists, verify encryption didn't fail on write
+
+4. **"Encryption too slow"**
+
+    - **Cause**: Using KMS with high latency
+    - **Fix**: Switch to AES for non-production, optimize KMS calls (batching)
+
+5. **"Credentials not encrypted after deployment"**
+    - **Cause**: `STAGE=dev` in production, or missing encryption keys
+    - **Fix**: Set `STAGE=production`, configure keys, redeploy
+
+**Getting Help**:
+
+-   Check logs for error details
+-   Review encryption-schema-registry.js configuration
+-   Verify environment variables
+-   Run health check: `curl http://localhost:3000/health/detailed`
+-   Check encryption status in health response
+
+---
+
+## References
+
+### Related Files
+
+**Core Encryption**:
+
+-   `packages/core/database/encryption/README.md` - Main encryption documentation
+-   `packages/core/database/encryption/encryption-schema-registry.js` - Encrypted fields definition
+-   `packages/core/database/encryption/field-encryption-service.js` - Field-level encryption (Prisma Extension)
+-   `packages/core/database/encryption/prisma-encryption-extension.js` - Prisma Client Extension
+-   `packages/core/encrypt/Cryptor.js` - Encryption adapter (KMS/AES)
+
+**DocumentDB**:
+
+-   `packages/core/database/documentdb-utils.js` - Raw query utilities
+-   `packages/core/database/prisma.js` - Prisma client initialization
+
+**Repositories**:
+
+-   `packages/core/user/repositories/user-repository-documentdb.js` - User repository
+-   `packages/core/modules/repositories/module-repository-documentdb.js` - Module/Entity repository
+-   `packages/core/credential/repositories/credential-repository-documentdb.js` - Credential repository
+-   `packages/core/integrations/repositories/integration-repository-documentdb.js` - Integration repository
+
+**Tests**:
+
+-   `packages/core/database/encryption/*.test.js` - Encryption unit tests
+-   `packages/core/**/repositories/__tests__/*.test.js` - Repository tests
+
+---
+
+### External Documentation
+
+**Prisma**:
+
+-   [Prisma Client Extensions](https://www.prisma.io/docs/concepts/components/prisma-client/client-extensions)
+-   [Raw Database Access](https://www.prisma.io/docs/concepts/components/prisma-client/raw-database-access)
+-   [MongoDB Support](https://www.prisma.io/docs/concepts/database-connectors/mongodb)
+
+**AWS DocumentDB**:
+
+-   [AWS DocumentDB Documentation](https://docs.aws.amazon.com/documentdb/)
+-   [MongoDB Compatibility](https://docs.aws.amazon.com/documentdb/latest/developerguide/functional-differences.html)
+
+**AWS KMS**:
+
+-   [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/)
+-   [Envelope Encryption](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#enveloping)
+
+**Encryption Best Practices**:
+
+-   [OWASP Cryptographic Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html)
+-   [NIST Encryption Standards](https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines)
+
+---
+
+### Frigg Framework
+
+**Core Documentation**:
+
+-   [Frigg Framework Docs](https://docs.friggframework.org)
+-   [GitHub Repository](https://github.com/friggframework/frigg)
+-   [Community Slack](https://friggframework.org/#contact)
+
+**Related Issues**:
+
+-   GitHub Issue: DocumentDB encryption support [#TBD]
+-   GitHub PR: Implement DocumentDBEncryptionService [#TBD]
+
+---
+
+## Appendix
+
+### Glossary
+
+**Terms**:
+
+-   **DocumentDB**: AWS DocumentDB, a MongoDB-compatible database service
+-   **Prisma Extension**: Prisma feature that intercepts and modifies queries
+-   **Raw Query**: Low-level database command that bypasses Prisma ORM
+-   **Envelope Encryption**: Encryption pattern using data keys encrypted by master keys
+-   **KMS**: AWS Key Management Service
+-   **AES**: Advanced Encryption Standard (symmetric encryption)
+-   **Field-Level Encryption**: Encrypting individual fields within documents
+
+**Acronyms**:
+
+-   **DRY**: Don't Repeat Yourself
+-   **IAM**: Identity and Access Management
+-   **HSM**: Hardware Security Module
+-   **GDPR**: General Data Protection Regulation
+-   **PCI-DSS**: Payment Card Industry Data Security Standard
+-   **HIPAA**: Health Insurance Portability and Accountability Act
+
+---
+
+### Changelog
+
+| Version | Date       | Author | Changes               |
+| ------- | ---------- | ------ | --------------------- |
+| 1.0     | 2025-01-13 | System | Initial documentation |
+
+---
+
+## Conclusion
+
+This document provides a complete specification and implementation guide for the DocumentDBEncryptionService. Follow the phases sequentially, run all tests, and verify encryption at each step.
+
+**Remember**: This is a **CRITICAL SECURITY** implementation. OAuth credentials MUST be encrypted at rest. Take the time to implement correctly and test thoroughly.
+
+For questions or support, contact the Frigg team via GitHub issues or community Slack.
+
+---
+
+**Document Status**: ✅ Ready for Implementation