@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/database/encryption/README.md

@@ -13,7 +13,7 @@ This module provides **transparent field-level encryption** for sensitive data i
 -   ✅ **Hexagonal architecture**: Clean separation of concerns
 -   ✅ **AWS KMS support**: Enterprise-grade encryption with AWS Key Management Service
 -   ✅ **Local AES fallback**: Development mode using local encryption keys
--   ✅ **Environment-based**: Automatic bypass in dev/test/local environments
+-   ✅ **Fails closed**: A deployed stage with no key refuses to start; only local runs (`frigg start`, tests) skip encryption
 -   ✅ **Envelope encryption**: Secure key management pattern
 
 ## Architecture
@@ -107,18 +107,46 @@ AES_KEY=your-32-character-secret-key-here
 STAGE=production  # or development, staging, etc.
 ```
 
-**⚠️ Important**: Encryption is automatically **disabled** when `STAGE` is set to `dev`, `test`, or `local`, regardless of key configuration.
+### When Encryption Runs
 
-### Bypass Encryption
+The rule lives in `encryption-config.js` and is shared by the Prisma client, the DocumentDB encryption service, the integration-mapping helpers and the `/health/detailed` check. It depends on **where the code runs**, not on the stage name.
 
-To explicitly disable encryption:
+A process is **deployed** when it runs in AWS Lambda (`AWS_LAMBDA_FUNCTION_NAME` or `LAMBDA_TASK_ROOT` is set, or `AWS_EXECUTION_ENV` starts with `AWS_Lambda_`) or on another provider's platform (`FRIGG_PROVIDER` names a provider other than `aws`; provider-netlify's generated functions set `FRIGG_PROVIDER=netlify`), and is **not** a local run (`IS_OFFLINE=true` from serverless-offline / `frigg start`, `IS_LOCAL=true` from `serverless invoke local`, `NETLIFY_DEV=true` from `netlify dev`, or `JEST_WORKER_ID` from Jest). Everything else is **local**. Netlify's `SITE_ID`, `CONTEXT` and `NETLIFY` are build-time variables, so they are not used.
 
-```bash
-# Disable encryption (development only)
-STAGE=development  # or dev, test, local
+| Runtime | Key configured | `FRIGG_ENCRYPTION_DISABLED=true` | Result |
+| --- | --- | --- | --- |
+| Deployed, any stage (including `dev`) | `KMS_KEY_ARN` | any | Encrypt with KMS |
+| Deployed, any stage | `AES_KEY_ID` + `AES_KEY` | any | Encrypt with AES |
+| Deployed, any stage | `AES_KEY_ID` without `AES_KEY` | no | **Refuses to start** (`EncryptionConfigurationError`) |
+| Deployed, any stage | none | no | **Refuses to start** (`EncryptionConfigurationError`) |
+| Deployed, any stage | none | yes | Plaintext, with a warning on every cold start |
+| Local, `STAGE` (or `NODE_ENV`) is `dev`, `test` or `local` | any | any | Skipped |
+| Local, any other stage | `KMS_KEY_ARN` or `AES_KEY_ID` | any | Encrypt |
+| Local, any other stage | none | any | Plaintext, with a warning |
+
+KMS wins when both keys are set. A configured key always wins over `FRIGG_ENCRYPTION_DISABLED`: switching encryption off while a key exists would leave already-encrypted data unreadable, so the opt-out is ignored (with a warning).
+
+"Refuses to start" means the Prisma client is never created: the first database access on a cold start throws
+
+```
+EncryptionConfigurationError: [Frigg] No field-level encryption key is configured for stage "dev". A deployed Frigg app will not write credentials and other sensitive fields in plaintext. Fix: ...
+```
+
+and `/health/detailed` reports `checks.encryption.status: "unhealthy"` with the same message. If a key is configured but the encryption extension fails to initialise, the client also refuses to start rather than continuing without encryption.
+
+To encrypt a local run, use a stage other than `dev`, `test` or `local` and configure a key.
+
+### Running a Deployed Stage Without Encryption
+
+Only do this on purpose, for a stage that never holds real credentials. Either set it in the app definition:
+
+```javascript
+const appDefinition = {
+    encryption: { fieldLevelEncryptionMethod: 'none' },
+};
 ```
 
-Or simply don't configure any encryption keys. In Production field level encryption **must** be enabled.
+which the infrastructure builders turn into `FRIGG_ENCRYPTION_DISABLED=true` on every function, or set `FRIGG_ENCRYPTION_DISABLED=true` in the Lambda environment yourself. Every cold start logs a warning that sensitive fields are stored in plaintext. There is no default that does this.
 
 ## Encrypted Fields
 
@@ -553,8 +581,8 @@ class MyRepositoryDocumentDB {
 
 #### Configuration
 
-Uses the same environment variables and Cryptor as the Prisma Extension:
-- `STAGE`: Bypasses encryption for dev/test/local
+Uses the same rule (`encryption-config.js`, see [When Encryption Runs](#when-encryption-runs)) and Cryptor as the Prisma Extension. Constructing the service in a deployed runtime with no key throws `EncryptionConfigurationError`.
+- `STAGE`: Skips encryption for dev/test/local on local runs only
 - `KMS_KEY_ARN`: AWS KMS encryption (production)
 - `AES_KEY_ID` + `AES_KEY`: AES encryption (fallback)
 
@@ -615,10 +643,27 @@ curl http://localhost:3000/health/test-encryption
     "encryptionWorks": true
 }
 
-# Response when encryption disabled:
+# Response on a local run with STAGE=dev:
 {
     "status": "disabled",
-    "reason": "Encryption bypassed for stage: development"
+    "bypassed": true,
+    "runtime": "local",
+    "testResult": "Encryption bypassed for this stage"
+}
+
+# Response in a deployed stage with no key (the app itself refuses to start):
+{
+    "status": "unhealthy",
+    "mode": "none",
+    "runtime": "deployed",
+    "testResult": "[Frigg] No field-level encryption key is configured for stage \"dev\". ..."
+}
+
+# Response in a deployed stage with FRIGG_ENCRYPTION_DISABLED=true and no key:
+{
+    "status": "disabled",
+    "optedOut": true,
+    "testResult": "Encryption explicitly disabled (FRIGG_ENCRYPTION_DISABLED=true); sensitive fields are stored in plaintext"
 }
 ```
 
@@ -732,9 +777,10 @@ FRIGG_LOG_LEVEL=INFO
 **Check environment variables:**
 
 ```bash
-echo $STAGE              # Should be 'production' (not dev/test/local)
 echo $KMS_KEY_ARN        # Should be set (for KMS)
-echo $AES_KEY_ID         # Should be set (for AES)
+echo $AES_KEY_ID $AES_KEY  # Both should be set (for AES)
+echo $STAGE              # Local runs only: dev/test/local skip encryption
+echo $FRIGG_ENCRYPTION_DISABLED  # Should be unset
 ```
 
 **Check console logs:**
@@ -749,6 +795,22 @@ or
 [Frigg] Field-level encryption disabled
 ```
 
+### Deployed Stage Refuses to Start
+
+**Error: "EncryptionConfigurationError: [Frigg] No field-level encryption key is configured for stage ..."**
+
+The function runs in AWS and has neither `KMS_KEY_ARN` nor `AES_KEY_ID` + `AES_KEY`. Earlier versions skipped encryption on stages named `dev`, `test` or `local` and wrote plaintext when no key was set; deployed stages now refuse instead. Fix one of:
+
+1. Set `encryption: { fieldLevelEncryptionMethod: 'kms' }` in the app definition and redeploy. Frigg creates or discovers a KMS key and sets `KMS_KEY_ARN` on every function, whatever the stage name.
+2. Provide `AES_KEY_ID` and `AES_KEY` (32 characters) through the app definition's `environment` and the deploy environment.
+3. To keep the stage in plaintext on purpose, set `encryption: { fieldLevelEncryptionMethod: 'none' }` (or `FRIGG_ENCRYPTION_DISABLED=true`).
+
+Data written in plaintext before the key existed stays readable: reads leave values that are not in the encrypted `keyId:iv:cipher:encKey` format untouched, and the next write of each record encrypts it. Records that are never rewritten stay in plaintext until you re-save them.
+
+**Error: "[Frigg] AES_KEY_ID is set but AES_KEY is not"**
+
+Provide `AES_KEY` alongside `AES_KEY_ID`, or switch to KMS.
+
 ### AWS KMS Errors
 
 **Error: "User is not authorized to perform: kms:GenerateDataKey"**

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

@@ -225,7 +225,84 @@ Database (ENCRYPTED STORAGE) ✅ SECURE
 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)
+4. **Fails Closed**: Same rule as the Prisma client; a deployed runtime with no key throws, only local runs skip encryption
+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. loadCustomEncryptionSchema()
+2. config = getEncryptionConfig()   // encryption/encryption-config.js, shared with the Prisma client
+   - throws EncryptionConfigurationError in a deployed runtime with no key
+3. If !config.enabled (local dev/test/local stage, local run without keys,
+   or FRIGG_ENCRYPTION_DISABLED=true opt-out):
+   - Set this.cryptor = null
+   - Set this.enabled = false
+   - Return
+4. Create Cryptor({ shouldUseAws: config.method === 'kms' })
+5. Set this.enabled = true
+```
+
+**Environment Variables Used** (see "When Encryption Runs" in README.md):
+
+-   `AWS_LAMBDA_FUNCTION_NAME` / `LAMBDA_TASK_ROOT` / `AWS_EXECUTION_ENV=AWS_Lambda_*`, or a non-`aws` `FRIGG_PROVIDER`, minus `IS_OFFLINE` / `IS_LOCAL` / `NETLIFY_DEV` / `JEST_WORKER_ID`: deployed or local run
+-   `STAGE` or `NODE_ENV`: dev/test/local skip encryption on local runs only
+-   `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 with AES_KEY_ID in a deployed runtime)
+-   `FRIGG_ENCRYPTION_DISABLED`: explicit plaintext opt-out for a deployed stage with no key
+
+### 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. **Fails Closed**: Same rule as the Prisma client; a deployed runtime with no key throws, only local runs skip encryption
 5. **Error-Tolerant**: Graceful handling of decryption failures
 6. **Testable**: Can be unit tested independently of repositories
 

package/database/encryption/encryption-config.js

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

package/database/encryption/encryption-schema-registry.js

@@ -39,6 +39,12 @@ const CORE_ENCRYPTION_SCHEMA = {
     Token: {
         fields: ['token'],
     },
+
+    // Multi-step authorization (Management API v2): earlier steps can collect
+    // emails, usernames or one-time codes.
+    AuthorizationSession: {
+        fields: ['stepData'],
+    },
 };
 
 let customSchema = {};
@@ -174,6 +180,13 @@ function loadModuleEncryptionSchemas(integrations) {
         return;
     }
 
+    // NOTE: this path does not exist ('../integrations' resolves to
+    // database/integrations), so today this function throws MODULE_NOT_FOUND,
+    // loadCustomEncryptionSchema swallows it, and module credentialFields are
+    // effectively NOT registered. Fixing it changes which fields are encrypted
+    // and needs a decrypt that tolerates plaintext, so it ships separately:
+    // branch claude/internal-mcp-03b-module-credential-encryption. Left as is
+    // here on purpose (ADR-059 must not change what gets encrypted).
     const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
 
     const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
@@ -205,22 +218,80 @@ function loadModuleEncryptionSchemas(integrations) {
  *
  * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
  */
-function loadCustomEncryptionSchema() {
-    try {
-        // Lazy require to avoid circular dependency issues
-        const path = require('node:path');
-        const { findNearestBackendPackageJson } = require('../../utils');
+/**
+ * Registers encryption schemas declared by app-level extensions
+ * (`appDefinition.coreExtensions[].encryption`), e.g. the db-credentials
+ * extension's `OAuthAppCredential.clientSecret`.
+ *
+ * @param {Array<Object>} extensions - Normalized extensions (extension-loader)
+ */
+function loadExtensionEncryptionSchemas(extensions) {
+    if (!extensions || !Array.isArray(extensions) || extensions.length === 0) {
+        return;
+    }
+
+    for (const ext of extensions) {
+        if (!ext.encryption || typeof ext.encryption !== 'object') {
+            continue;
+        }
+
+        const schema = {};
+        for (const [modelName, config] of Object.entries(ext.encryption)) {
+            if (config && Array.isArray(config.fields) && config.fields.length > 0) {
+                schema[modelName] = { fields: config.fields };
+            }
+        }
 
-        const backendPackagePath = findNearestBackendPackageJson();
-        if (!backendPackagePath) {
-            return; // No backend found, skip custom schema
+        if (Object.keys(schema).length > 0) {
+            logger.info(
+                `Registering encryption schema from extension "${ext.name}" for models: ${Object.keys(schema).join(', ')}`
+            );
+            // registerCustomSchema replaces the registered schema, so merge:
+            // an extension adds its models to the app's encryption.schema
+            // rather than dropping it.
+            const merged = { ...customSchema };
+            for (const [modelName, config] of Object.entries(schema)) {
+                const existing = merged[modelName]?.fields || [];
+                merged[modelName] = {
+                    ...merged[modelName],
+                    fields: [...new Set([...existing, ...config.fields])],
+                };
+            }
+            registerCustomSchema(merged);
         }
+    }
+}
 
-        const backendDir = path.dirname(backendPackagePath);
-        const backendIndexPath = path.join(backendDir, 'index.js');
+function readAppDefinitionForEncryption() {
+    // Lazy require to avoid circular dependency issues
+    const {
+        getPresetAppDefinition,
+    } = require('../../handlers/app-definition-loader');
+    // A definition preset with setAppDefinition() (provider-netlify's
+    // preamble) wins: on Netlify process.cwd() cannot find the backend.
+    const preset = getPresetAppDefinition();
+    if (preset) {
+        return preset;
+    }
+
+    const path = require('node:path');
+    const { findNearestBackendPackageJson } = require('../../utils');
+
+    const backendPackagePath = findNearestBackendPackageJson();
+    if (!backendPackagePath) {
+        return null; // No backend found, skip custom schema
+    }
 
-        const backendModule = require(backendIndexPath);
-        const appDefinition = backendModule?.Definition;
+    const backendDir = path.dirname(backendPackagePath);
+    const backendIndexPath = path.join(backendDir, 'index.js');
+
+    const backendModule = require(backendIndexPath);
+    return backendModule?.Definition || null;
+}
+
+function loadCustomEncryptionSchema() {
+    try {
+        const appDefinition = readAppDefinitionForEncryption();
 
         if (!appDefinition) {
             return; // No app definition found
@@ -240,6 +311,15 @@ function loadCustomEncryptionSchema() {
             registerEncryptionOptOut(disable);
         }
 
+        // Load app-level extension encryption schemas. Before the module
+        // schemas: loadModuleEncryptionSchemas currently throws (see the
+        // NOTE inside it) and the throw would skip anything after it.
+        const { loadExtensions } = require('../../extensions/extension-loader');
+        const extensions = loadExtensions(appDefinition);
+        if (extensions.length > 0) {
+            loadExtensionEncryptionSchemas(extensions);
+        }
+
         // Load module-level encryption schemas from integrations
         const integrations = appDefinition.integrations;
         if (integrations && Array.isArray(integrations)) {
@@ -396,6 +476,7 @@ module.exports = {
     registerEncryptionOptOut,
     loadCustomEncryptionSchema,
     loadModuleEncryptionSchemas,
+    loadExtensionEncryptionSchemas,
     extractCredentialFieldsFromModules,
     validateCustomSchema,
     validateOptOut,

package/database/encryption/integration-mapping-encryption.js

@@ -1,4 +1,4 @@
-const { getEncryptionConfig } = require('../prisma');
+const { getEncryptionConfig } = require('./encryption-config');
 const { Cryptor } = require('../../encrypt/Cryptor');
 const {
     getFieldsToDecryptOnRead,

package/database/organization-where.js

@@ -0,0 +1,18 @@
+/**
+ * The Prisma `where` fragment for an `organizationId` on MongoDB (ADR-056
+ * §3.6), shared by the entity and integration adapters.
+ *
+ * Prisma on MongoDB: `null` matches only an explicit null and `isSet: false`
+ * only a missing field. A row written before the column existed is the common
+ * "no organization" case, so `null` here means both.
+ */
+function organizationWhere(organizationId) {
+    if (organizationId === null) {
+        return {
+            OR: [{ organizationId: null }, { organizationId: { isSet: false } }],
+        };
+    }
+    return { organizationId };
+}
+
+module.exports = { organizationWhere };