@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.680.daae24e.0

package/database/documentdb-encryption-service.js

@@ -4,6 +4,7 @@ const {
     getFieldsToEncryptOnWrite,
     loadCustomEncryptionSchema,
 } = require('./encryption/encryption-schema-registry');
+const { getEncryptionConfig } = require('./encryption/encryption-config');
 
 /**
  * Encryption service specifically for DocumentDB repositories
@@ -41,43 +42,29 @@ class DocumentDBEncryptionService {
     }
 
     /**
-     * Initialize Cryptor with environment-based configuration.
-     * Matches the logic from @friggframework/core/database/prisma.js
+     * Initialize Cryptor with environment-based configuration, using the
+     * same rule as the Prisma client (see encryption/encryption-config.js).
      *
-     * Encryption is bypassed in dev/test/local stages.
-     * Production uses AWS KMS (if available) or AES encryption.
+     * Local runs skip encryption on the dev, test and local stages. A
+     * deployed runtime with no key throws instead of writing plaintext.
      *
      * @private
+     * @throws {EncryptionConfigurationError} deployed with no usable key
      */
     _initializeCryptor() {
         // Load custom encryption schema from app definition BEFORE checking configuration
         // This ensures custom fields (like User.username) are registered before any encryption operations
         loadCustomEncryptionSchema();
 
-        // Match logic from packages/core/database/prisma.js
-        const stage = process.env.STAGE || process.env.NODE_ENV || 'development';
-        const bypassEncryption = ['dev', 'test', 'local'].includes(stage.toLowerCase());
+        const config = getEncryptionConfig();
 
-        if (bypassEncryption) {
+        if (!config.enabled) {
             this.cryptor = null;
             this.enabled = false;
             return;
         }
 
-        // Determine encryption method (ensure boolean values)
-        const hasKMS = !!(process.env.KMS_KEY_ARN && process.env.KMS_KEY_ARN.trim() !== '');
-        const hasAES = !!(process.env.AES_KEY_ID && process.env.AES_KEY_ID.trim() !== '');
-
-        if (!hasKMS && !hasAES) {
-            console.warn('[DocumentDBEncryptionService] No encryption keys configured. Encryption disabled.');
-            this.cryptor = null;
-            this.enabled = false;
-            return;
-        }
-
-        // KMS takes precedence over AES
-        const shouldUseAws = hasKMS;
-        this.cryptor = new Cryptor({ shouldUseAws });
+        this.cryptor = new Cryptor({ shouldUseAws: config.method === 'kms' });
         this.enabled = true;
     }
 

package/database/documentdb-utils.js

@@ -58,10 +58,7 @@ async function insertOne(client, collection, document) {
 
         // Provide helpful context for common errors
         if (error.code === 11000) {
-            throw Object.assign(
-                new Error(`${errorMsg} - Duplicate key violation`),
-                { code: 11000 }
-            );
+            throw new Error(`${errorMsg} - Duplicate key violation`);
         }
         throw new Error(errorMsg);
     }

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.
+
+| 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
 
-```bash
-# Disable encryption (development only)
-STAGE=development  # or dev, test, local
 ```
+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
 
-Or simply don't configure any encryption keys. In Production field level encryption **must** be enabled.
+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' },
+};
+```
+
+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
 
@@ -428,6 +456,8 @@ Format: "keyId:encryptedText:encryptedKey"
 Example: "base64KeyId:iv:ciphertext:base64EncryptedDataKey"
 ```
 
+**Recognising ciphertext on read.** A value is decrypted only when it has exactly four colon-separated parts: base64 `keyId`, 32-hex-character `iv`, hex ciphertext, base64 `encryptedKey`. Plaintext that merely contains colons (`https://user:pw@host:443`) is left alone. A value with that shape that still fails to decrypt (a wrong, rotated or missing key) fails the read with `FieldDecryptionError` in a deployed runtime (see [When Encryption Runs](#when-encryption-runs)), so ciphertext never reaches an API module as if it were a token. Locally it is returned as stored and logged as a warning, so one bad field does not fail a whole read. A field that becomes encrypted later (for example a module's `credentialFields`) stays plaintext in existing rows until they are next written.
+
 **Why Envelope Encryption?**
 
 -   Reduces KMS API calls (one DEK per field, cached)
@@ -553,8 +583,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 +645,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 +779,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 +797,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,240 @@
+/**
+ * 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 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
+ * another provider's platform.
+ *
+ * - AWS Lambda sets AWS_LAMBDA_FUNCTION_NAME, LAMBDA_TASK_ROOT and
+ *   AWS_EXECUTION_ENV (AWS_Lambda_<runtime>). Other AWS hosts (CloudShell,
+ *   CodeBuild, ECS) set AWS_EXECUTION_ENV to other values and count as local:
+ *   CLI commands run from CI must not trip the deployed-stage check.
+ * - Other providers: FRIGG_PROVIDER names a non-AWS provider. Frigg's
+ *   generated function entry points for that provider set it (provider-netlify
+ *   sets 'netlify'), so it is present in every deployed function. Netlify
+ *   exposes SITE_ID, CONTEXT and NETLIFY at build time only, so they cannot
+ *   tell a running function from a laptop.
+ *
+ * A local run is never deployed: serverless-offline and `serverless invoke
+ * local` (which set the Lambda variables themselves) mark IS_OFFLINE /
+ * IS_LOCAL, `netlify dev` marks NETLIFY_DEV, and Jest marks JEST_WORKER_ID.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function isDeployedRuntime(env = process.env) {
+    const localRun =
+        isTrue(env.IS_OFFLINE) ||
+        isTrue(env.IS_LOCAL) ||
+        isTrue(env.NETLIFY_DEV) ||
+        isSet(env.JEST_WORKER_ID);
+    if (localRun) return false;
+
+    const onAwsRuntime =
+        isSet(env.AWS_LAMBDA_FUNCTION_NAME) ||
+        isSet(env.LAMBDA_TASK_ROOT) ||
+        String(env.AWS_EXECUTION_ENV ?? '').startsWith('AWS_Lambda_');
+    if (onAwsRuntime) return true;
+
+    const provider = String(env.FRIGG_PROVIDER ?? '').trim().toLowerCase();
+    return provider !== '' && provider !== 'aws';
+}
+
+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

@@ -10,6 +10,11 @@
 
 const { logger } = require('./logger');
 const { registerDeniedKeys } = require('../../logs/denied-keys');
+const {
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+    EntityRegistryError,
+} = require('../../modules/entity-type-registry');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -39,6 +44,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 = {};
@@ -160,8 +171,9 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
  * Each module can declare credentialFields to encrypt in its encryption config.
  *
  * @param {Array} integrations - Array of integration classes with modules
+ * @param {object} [entities] - `appDefinition.entities` (ADR-059 registry)
  */
-function loadModuleEncryptionSchemas(integrations) {
+function loadModuleEncryptionSchemas(integrations, entities) {
     if (!integrations) {
         throw new Error('integrations parameter is required');
     }
@@ -170,27 +182,39 @@ function loadModuleEncryptionSchemas(integrations) {
         throw new Error('integrations must be an array');
     }
 
-    if (integrations.length === 0) {
+    // `entities` is the app definition's registry (ADR-059): a module an app
+    // registers without any integration still carries credentials to encrypt.
+    if (integrations.length === 0 && !entities) {
         return;
     }
 
-    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
-
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
+    const moduleDefinitions = getEntityTypeDefinitions(
+        getEntityTypeRegistry({ integrations, entities })
+    );
     const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
 
-    if (credentialFields.length === 0) {
+    // Core fields are encrypted already and a custom schema may not repeat
+    // them. Everything the app registered itself stays: module fields are added
+    // to the custom schema, never substituted for it (other models included).
+    const coreFields = new Set(CORE_ENCRYPTION_SCHEMA.Credential?.fields || []);
+    const fields = [
+        ...new Set([
+            ...(customSchema.Credential?.fields || []),
+            ...credentialFields.filter((field) => !coreFields.has(field)),
+        ]),
+    ];
+
+    if (fields.length === 0) {
         return;
     }
 
     const moduleSchema = {
-        Credential: {
-            fields: credentialFields
-        }
+        ...customSchema,
+        Credential: { ...customSchema.Credential, fields },
     };
 
     logger.info(
-        `Registering module-level encryption for ${credentialFields.length} credential fields`
+        `Registering module-level encryption for ${fields.length} credential fields`
     );
 
     registerCustomSchema(moduleSchema);
@@ -242,10 +266,15 @@ function loadCustomEncryptionSchema() {
 
         // Load module-level encryption schemas from integrations
         const integrations = appDefinition.integrations;
-        if (integrations && Array.isArray(integrations)) {
-            loadModuleEncryptionSchemas(integrations);
+        if (Array.isArray(integrations) || appDefinition.entities) {
+            loadModuleEncryptionSchemas(
+                Array.isArray(integrations) ? integrations : [],
+                appDefinition.entities
+            );
         }
     } catch (error) {
+        // A bad entity registry is a configuration error, not "no custom schema".
+        if (error instanceof EntityRegistryError) throw error;
         // Silently ignore errors - custom schema is optional
         // This handles cases like:
         // - Backend package.json not found (tests, standalone usage)