@friggframework/core 2.0.0--canary.663.9683f8b.0 → 2.0.0--canary.664.a0b36e4.0

package/database/documentdb-encryption-service.js

@@ -4,7 +4,6 @@ const {
     getFieldsToEncryptOnWrite,
     loadCustomEncryptionSchema,
 } = require('./encryption/encryption-schema-registry');
-const { getEncryptionConfig } = require('./encryption/encryption-config');
 
 /**
  * Encryption service specifically for DocumentDB repositories
@@ -42,29 +41,43 @@ class DocumentDBEncryptionService {
     }
 
     /**
-     * Initialize Cryptor with environment-based configuration, using the
-     * same rule as the Prisma client (see encryption/encryption-config.js).
+     * Initialize Cryptor with environment-based configuration.
+     * Matches the logic from @friggframework/core/database/prisma.js
      *
-     * Local runs skip encryption on the dev, test and local stages. A
-     * deployed runtime with no key throws instead of writing plaintext.
+     * Encryption is bypassed in dev/test/local stages.
+     * Production uses AWS KMS (if available) or AES encryption.
      *
      * @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();
 
-        const config = getEncryptionConfig();
+        // 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());
 
-        if (!config.enabled) {
+        if (bypassEncryption) {
             this.cryptor = null;
             this.enabled = false;
             return;
         }
 
-        this.cryptor = new Cryptor({ shouldUseAws: config.method === 'kms' });
+        // 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.enabled = true;
     }
 

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
--   ✅ **Fails closed**: A deployed stage with no key refuses to start; only local runs (`frigg start`, tests) skip encryption
+-   ✅ **Environment-based**: Automatic bypass in dev/test/local environments
 -   ✅ **Envelope encryption**: Secure key management pattern
 
 ## Architecture
@@ -107,46 +107,18 @@ AES_KEY=your-32-character-secret-key-here
 STAGE=production  # or development, staging, etc.
 ```
 
-### When Encryption Runs
+**⚠️ Important**: Encryption is automatically **disabled** when `STAGE` is set to `dev`, `test`, or `local`, regardless of key configuration.
 
-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.
+### Bypass 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_`) and is **not** a local run (`IS_OFFLINE=true` from serverless-offline / `frigg start`, `IS_LOCAL=true` from `serverless invoke local`, or `JEST_WORKER_ID` from Jest). Everything else is **local**.
+To explicitly disable encryption:
 
-| 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' },
-};
+```bash
+# Disable encryption (development only)
+STAGE=development  # or dev, test, local
 ```
 
-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.
+Or simply don't configure any encryption keys. In Production field level encryption **must** be enabled.
 
 ## Encrypted Fields
 
@@ -581,8 +553,8 @@ class MyRepositoryDocumentDB {
 
 #### Configuration
 
-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
+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)
 
@@ -643,27 +615,10 @@ curl http://localhost:3000/health/test-encryption
     "encryptionWorks": true
 }
 
-# Response on a local run with STAGE=dev:
+# Response when encryption disabled:
 {
     "status": "disabled",
-    "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"
+    "reason": "Encryption bypassed for stage: development"
 }
 ```
 
@@ -777,10 +732,9 @@ 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 $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
+echo $AES_KEY_ID         # Should be set (for AES)
 ```
 
 **Check console logs:**
@@ -795,22 +749,6 @@ 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,84 +225,7 @@ 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. **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_*`, minus `IS_OFFLINE` / `IS_LOCAL` / `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
+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
 

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

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

package/database/prisma.js

@@ -4,7 +4,6 @@ const {
 const { loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
 const { logger } = require('./encryption/logger');
 const { Cryptor } = require('../encrypt/Cryptor');
-const { getEncryptionConfig } = require('./encryption/encryption-config');
 const config = require('./config');
 
 /**
@@ -33,6 +32,33 @@ function ensureMongoDbUrl() {
     );
 }
 
+function getEncryptionConfig() {
+    const STAGE = process.env.STAGE || process.env.NODE_ENV || 'development';
+    const shouldBypassEncryption = ['dev', 'test', 'local'].includes(STAGE);
+
+    if (shouldBypassEncryption) {
+        return { enabled: false };
+    }
+
+    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) {
+        logger.warn(
+            'No encryption keys configured (KMS_KEY_ARN or AES_KEY_ID). ' +
+            'Field-level encryption disabled. Set STAGE=production and configure keys to enable.'
+        );
+        return { enabled: false };
+    }
+
+    return {
+        enabled: true,
+        method: hasKMS ? 'kms' : 'aes',
+    };
+}
+
 const prismaClientSingleton = () => {
     let PrismaClient;
 
@@ -77,13 +103,9 @@ const prismaClientSingleton = () => {
         errorFormat: 'pretty',
     });
 
-    // Throws when a deployed runtime has no encryption key: the app must not
-    // start and write sensitive fields in plaintext.
     const encryptionConfig = getEncryptionConfig();
 
     if (encryptionConfig.enabled) {
-        // Fail closed: if the extension cannot be installed, do not hand out
-        // a client that would write plaintext.
         try {
             // Load custom encryption schema from appDefinition before creating extension
             loadCustomEncryptionSchema();
@@ -98,14 +120,17 @@ const prismaClientSingleton = () => {
                     enabled: true,
                 })
             );
+
+            logger.info(
+                `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
+            );
         } catch (error) {
-            logger.error('Failed to initialize encryption extension:', error);
-            throw error;
+            logger.error(
+                'Failed to initialize encryption extension:',
+                error
+            );
+            logger.warn('Continuing without encryption...');
         }
-
-        logger.info(
-            `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
-        );
     } else {
         logger.info('Field-level encryption disabled');
     }

package/database/use-cases/check-encryption-health-use-case.js

@@ -1,12 +1,3 @@
-const {
-    resolveEncryptionConfig,
-    OPT_OUT_VAR,
-} = require('../encryption/encryption-config');
-
-/**
- * Reports whether field-level encryption is on and working, using the same
- * rule the Prisma client applies at startup (encryption/encryption-config.js).
- */
 class CheckEncryptionHealthUseCase {
     constructor({ testEncryptionUseCase }) {
         this.testEncryptionUseCase = testEncryptionUseCase;
@@ -14,60 +5,78 @@ class CheckEncryptionHealthUseCase {
 
     async execute() {
         const config = this._getEncryptionConfiguration();
-        const summary = {
-            mode: config.mode,
-            bypassed: config.bypassed,
-            optedOut: config.optedOut,
-            runtime: config.runtime,
-            stage: config.stage,
-            debug: {
-                hasKMS: config.hasKMS,
-                hasAES: config.hasAES,
-            },
-        };
 
-        if (config.error) {
-            return {
-                status: 'unhealthy',
-                ...summary,
-                testResult: config.error,
-                encryptionWorks: false,
-            };
-        }
+        if (config.isBypassed || config.mode === 'none') {
+            const testResult = config.isBypassed
+                ? 'Encryption bypassed for this stage'
+                : 'No encryption keys configured';
 
-        if (!config.enabled) {
             return {
                 status: 'disabled',
-                ...summary,
-                testResult: this._disabledReason(config),
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                testResult,
                 encryptionWorks: false,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
             };
         }
 
         try {
             const testResults = await this.testEncryptionUseCase.execute();
-            return { ...testResults, ...summary };
+
+            return {
+                ...testResults,
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
+            };
         } catch (error) {
             return {
                 status: 'unhealthy',
-                ...summary,
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
                 testResult: `Encryption test failed: ${error.message}`,
                 encryptionWorks: false,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
             };
         }
     }
 
-    _disabledReason(config) {
-        if (config.bypassed) return 'Encryption bypassed for this stage';
-        if (config.optedOut) {
-            return `Encryption explicitly disabled (${OPT_OUT_VAR}=true); sensitive fields are stored in plaintext`;
-        }
-        return 'No encryption keys configured';
-    }
-
     _getEncryptionConfiguration() {
-        const config = resolveEncryptionConfig(process.env);
-        return { ...config, stage: process.env.STAGE || null };
+        const { STAGE, BYPASS_ENCRYPTION_STAGE, KMS_KEY_ARN, AES_KEY_ID } =
+            process.env;
+
+        const defaultBypassStages = ['dev', 'test', 'local'];
+        const useEnv = BYPASS_ENCRYPTION_STAGE !== undefined;
+        const bypassStages = useEnv
+            ? BYPASS_ENCRYPTION_STAGE.split(',').map((s) => s.trim())
+            : defaultBypassStages;
+
+        const isBypassed = bypassStages.includes(STAGE);
+        const hasAES = AES_KEY_ID && AES_KEY_ID.trim() !== '';
+        const hasKMS = KMS_KEY_ARN && KMS_KEY_ARN.trim() !== '';
+        // Prefer KMS over AES when both are configured (KMS is more secure)
+        const mode = hasKMS ? 'kms' : hasAES ? 'aes' : 'none';
+
+        return {
+            stage: STAGE || null,
+            isBypassed,
+            hasAES,
+            hasKMS,
+            mode,
+        };
     }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.663.9683f8b.0",
+    "version": "2.0.0--canary.664.a0b36e4.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.663.9683f8b.0",
-        "@friggframework/prettier-config": "2.0.0--canary.663.9683f8b.0",
-        "@friggframework/test": "2.0.0--canary.663.9683f8b.0",
+        "@friggframework/eslint-config": "2.0.0--canary.664.a0b36e4.0",
+        "@friggframework/prettier-config": "2.0.0--canary.664.a0b36e4.0",
+        "@friggframework/test": "2.0.0--canary.664.a0b36e4.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "9683f8b4ecbbb8a91b497c63e04277490769bad8"
+    "gitHead": "a0b36e4677d1a9b2b0387e9b2b6b59ab76cf8098"
 }

package/database/encryption/encryption-config.js

@@ -1,227 +0,0 @@
-/**
- * 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 in AWS Lambda for real. The Lambda runtime sets
- * AWS_LAMBDA_FUNCTION_NAME, LAMBDA_TASK_ROOT and AWS_EXECUTION_ENV
- * (AWS_Lambda_<runtime>). serverless-offline sets the first two as well, so
- * IS_OFFLINE, IS_LOCAL and Jest mark a local run. Other AWS hosts (CloudShell,
- * CodeBuild, ECS) set AWS_EXECUTION_ENV to other values and count as local:
- * Frigg deploys its handlers to Lambda only, and CLI commands run from CI must
- * not trip the deployed-stage check.
- *
- * @param {Object} [env=process.env]
- * @returns {boolean}
- */
-function isDeployedRuntime(env = process.env) {
-    const onAwsRuntime =
-        isSet(env.AWS_LAMBDA_FUNCTION_NAME) ||
-        isSet(env.LAMBDA_TASK_ROOT) ||
-        String(env.AWS_EXECUTION_ENV ?? '').startsWith('AWS_Lambda_');
-    if (!onAwsRuntime) return false;
-
-    const localRun =
-        isTrue(env.IS_OFFLINE) ||
-        isTrue(env.IS_LOCAL) ||
-        isSet(env.JEST_WORKER_ID);
-    return !localRun;
-}
-
-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,
-};