@friggframework/core 2.0.0--canary.703.6a9383b.0 → 2.0.0--canary.680.daae24e.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# Unreleased
+
+#### Behaviour change: module credential fields are now encrypted
+
+- `credentialFields` declared in an API module's `encryption` config (for example `Definition.encryption.credentialFields`) were never registered for encryption: `loadModuleEncryptionSchemas` required a path that does not exist and the error was swallowed. They are now registered, for modules bound by integrations and for modules registered in `appDefinition.entities` (ADR-059).
+- Existing rows are not rewritten. A credential saved before this release stays plaintext until it is next written, and is read as stored.
+- Reads now tolerate plaintext: a value is only treated as ciphertext when it has the exact `keyId:iv:ciphertext:encryptedKey` shape (previously any string with three or more colons, such as `https://user:pw@host:443`), and a value with that shape that fails to decrypt throws `FieldDecryptionError` in a deployed runtime (any stage, AWS Lambda or Netlify) and is returned as stored with a warning on a local run.
+- An app's own `encryption.schema` is no longer replaced when module fields are added to it.
+
+---
+
 # v1.2.2 (Fri Aug 09 2024)
 
 #### 🐛 Bug Fix

package/application/commands/integration-commands.js

@@ -30,8 +30,9 @@ const {
     PatchIntegrationConfig,
 } = require('../../integrations/use-cases/patch-integration-config');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+} = require('../../modules/entity-type-registry');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 401,
@@ -51,7 +52,16 @@ function mapErrorToResponse(error) {
     };
 }
 
-function createIntegrationCommands({ integrationClass } = {}) {
+/**
+ * @param {Object} [params]
+ * @param {Function} [params.integrationClass]
+ * @param {Array<object>} [params.moduleDefinitions] - the app's offered module
+ *   definitions (`loadAppDefinition().moduleDefinitions`). Integration code
+ *   calls this from a constructor with no app definition in hand, so when it
+ *   is omitted the commands hydrate with this integration's own modules only
+ *   (a registry built from `{ integrations: [integrationClass] }`).
+ */
+function createIntegrationCommands({ integrationClass, moduleDefinitions } = {}) {
     // Always use Frigg's default repositories and use cases
     const integrationRepository = createIntegrationRepository();
 
@@ -108,13 +118,13 @@ function createIntegrationCommands({ integrationClass } = {}) {
 
     const moduleRepository = createModuleRepository();
 
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses([
-        integrationClass,
-    ]);
-
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions,
+        moduleDefinitions:
+            moduleDefinitions ??
+            getEntityTypeDefinitions(
+                getEntityTypeRegistry({ integrations: [integrationClass] })
+            ),
     });
 
     const loadIntegrationContextUseCase = new LoadIntegrationContextUseCase({

package/application/index.js

@@ -17,6 +17,7 @@ const { createUsageCommands } = require('./commands/usage-commands');
  *
  * @param {Object} params
  * @param {Object} params.integrationClass - Integration class (required)
+ * @param {Array<object>} [params.moduleDefinitions] - the app's offered module definitions; defaults to the integration's own modules
  * @returns {Object} Unified commands object with all CRUD operations
  *
  * @example
@@ -24,9 +25,12 @@ const { createUsageCommands } = require('./commands/usage-commands');
  * const user = await commands.createUser({ username: 'user@example.com' });
  * const credential = await commands.createCredential({ userId: user.id, ... });
  */
-function createFriggCommands({ integrationClass }) {
+function createFriggCommands({ integrationClass, moduleDefinitions }) {
     // All commands use Frigg's default repositories and use cases
-    const integrationCommands = createIntegrationCommands({ integrationClass });
+    const integrationCommands = createIntegrationCommands({
+        integrationClass,
+        moduleDefinitions,
+    });
 
     const userCommands = createUserCommands();
 

package/credential/repositories/credential-repository-documentdb.js

@@ -186,6 +186,40 @@ class CredentialRepositoryDocumentDB extends CredentialRepositoryInterface {
         return this._mapCredential(decryptedCredential);
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string} userId - User ID
+     * @returns {Promise<Array<Object>>} Credentials with string IDs
+     */
+    async findCredentialsByUserId(userId) {
+        const userObjectId = toObjectId(userId);
+        if (!userObjectId) return [];
+        const docs = await findManyDrained(
+            this.prisma,
+            'Credential',
+            { userId: userObjectId },
+            { sort: { createdAt: -1 } }
+        );
+        const credentials = [];
+        for (const doc of docs) {
+            const decrypted = await this.encryptionService.decryptFields(
+                'Credential',
+                doc
+            );
+            credentials.push({
+                ...this._mapCredential(decrypted),
+                id: fromObjectId(doc._id),
+                userId: fromObjectId(doc.userId) ?? doc.userId,
+                externalId: doc.externalId ?? null,
+                authIsValid: doc.authIsValid ?? null,
+                createdAt: doc.createdAt ?? null,
+                updatedAt: doc.updatedAt ?? null,
+            });
+        }
+        return credentials;
+    }
+
     async updateCredential(credentialId, updates) {
         const objectId = toObjectId(credentialId);
         if (!objectId) return null;

package/credential/repositories/credential-repository-interface.js

@@ -80,6 +80,21 @@ class CredentialRepositoryInterface {
         );
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string|number} userId - User ID (string from application layer)
+     * @returns {Promise<Array<Object>>} Credentials with string IDs, `createdAt`
+     *   and `updatedAt`, and the (decrypted) data fields spread in, as
+     *   findCredentialById returns them. Empty when the user has none.
+     * @abstract
+     */
+    async findCredentialsByUserId(userId) {
+        throw new Error(
+            'Method findCredentialsByUserId must be implemented by subclass'
+        );
+    }
+
     /**
      * Update a credential by ID
      *

package/credential/repositories/credential-repository-mongo.js

@@ -188,6 +188,29 @@ class CredentialRepositoryMongo extends CredentialRepositoryInterface {
         };
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string} userId - User ID
+     * @returns {Promise<Array<Object>>} Credentials with string IDs
+     */
+    async findCredentialsByUserId(userId) {
+        if (!userId) return [];
+        const credentials = await this.prisma.credential.findMany({
+            where: { userId: String(userId) },
+            orderBy: { createdAt: 'desc' },
+        });
+        return credentials.map((credential) => ({
+            ...(credential.data || {}),
+            id: credential.id,
+            userId: credential.userId,
+            externalId: credential.externalId,
+            authIsValid: credential.authIsValid,
+            createdAt: credential.createdAt,
+            updatedAt: credential.updatedAt,
+        }));
+    }
+
     /**
      * Update a credential by ID
      * Replaces: Credential.findByIdAndUpdate(credentialId, { $set: updates })

package/credential/repositories/credential-repository-postgres.js

@@ -205,6 +205,34 @@ class CredentialRepositoryPostgres extends CredentialRepositoryInterface {
         };
     }
 
+    /**
+     * All credentials owned by a user, newest first.
+     *
+     * @param {string} userId - User ID (string from application layer)
+     * @returns {Promise<Array<Object>>} Credentials with string IDs
+     */
+    async findCredentialsByUserId(userId) {
+        let intUserId;
+        try {
+            intUserId = this._convertId(userId);
+        } catch {
+            return [];
+        }
+        const credentials = await this.prisma.credential.findMany({
+            where: { userId: intUserId },
+            orderBy: { createdAt: 'desc' },
+        });
+        return credentials.map((credential) => ({
+            ...(credential.data || {}),
+            id: credential.id.toString(),
+            userId: credential.userId?.toString(),
+            externalId: credential.externalId,
+            authIsValid: credential.authIsValid,
+            createdAt: credential.createdAt,
+            updatedAt: credential.updatedAt,
+        }));
+    }
+
     /**
      * Update a credential by ID
      *

package/credential/use-cases/credential-operations-for-user.js

@@ -0,0 +1,117 @@
+const Boom = require('@hapi/boom');
+const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
+
+/**
+ * Management API v2 credential operations. A credential has no module name
+ * of its own; its `type` and the entities that use it come from the
+ * caller's entities. A missing or foreign credential is a 404.
+ */
+
+const credentialIdOf = (entity) => {
+    const ref = entity.credential ?? entity.credentialId;
+    if (ref === undefined || ref === null) return null;
+    if (typeof ref === 'object') {
+        const id = ref.id ?? ref._id;
+        return id === undefined || id === null ? null : String(id);
+    }
+    return String(ref);
+};
+
+/** Adds `type` and `entityIds` from the user's entities to each credential. */
+function withEntityUsage(credentials, entities) {
+    const usage = new Map();
+    for (const entity of entities || []) {
+        const credentialId = credentialIdOf(entity);
+        if (!credentialId) continue;
+        const entry = usage.get(credentialId) || { type: null, entityIds: [] };
+        entry.type = entry.type || entity.moduleName || null;
+        entry.entityIds.push(String(entity.id));
+        usage.set(credentialId, entry);
+    }
+    return credentials.map((credential) => {
+        const entry = usage.get(String(credential.id)) || {
+            type: null,
+            entityIds: [],
+        };
+        return { ...credential, type: entry.type, entityIds: entry.entityIds };
+    });
+}
+
+/** The caller's credentials with their type and entity usage. */
+class ListCredentialsForUser {
+    constructor({ credentialRepository, moduleRepository }) {
+        this.credentialRepository = credentialRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute(user) {
+        const userId = user.getId();
+        const [credentials, entities] = await Promise.all([
+            this.credentialRepository.findCredentialsByUserId(userId),
+            this.moduleRepository.findEntitiesByUserId(userId),
+        ]);
+        return withEntityUsage(credentials || [], entities);
+    }
+}
+
+/** One credential the caller owns, with its type and entity usage. */
+class GetCredentialForUserV2 {
+    constructor({ credentialRepository, moduleRepository }) {
+        this.credentialRepository = credentialRepository;
+        this.moduleRepository = moduleRepository;
+    }
+
+    async execute(credentialId, user) {
+        let credential = null;
+        try {
+            credential = await this.credentialRepository.findCredentialById(
+                credentialId
+            );
+        } catch (error) {
+            if (!/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
+                throw error;
+            }
+        }
+        if (!credential || !userOwns(user, credential.userId)) {
+            throw Boom.notFound(`Credential ${credentialId} not found`, {
+                code: 'CREDENTIAL_NOT_FOUND',
+            });
+        }
+        const entities = await this.moduleRepository.findEntitiesByUserId(
+            credential.userId
+        );
+        return withEntityUsage([credential], entities)[0];
+    }
+}
+
+/**
+ * Deletes a credential the caller owns. The entities that used it stay, with
+ * their credential unset, so they show as needing re-authorization rather
+ * than disappearing from integrations.
+ */
+class DeleteCredentialForUser {
+    constructor({ credentialRepository, moduleRepository, getCredentialForUser }) {
+        this.credentialRepository = credentialRepository;
+        this.moduleRepository = moduleRepository;
+        this.getCredentialForUser = getCredentialForUser;
+    }
+
+    async execute(credentialId, user) {
+        const credential = await this.getCredentialForUser.execute(
+            credentialId,
+            user
+        );
+        for (const entityId of credential.entityIds) {
+            await this.moduleRepository.unsetCredential(entityId);
+        }
+        await this.credentialRepository.deleteCredentialById(credential.id);
+        return { id: String(credential.id), entityIds: credential.entityIds };
+    }
+}
+
+module.exports = {
+    ListCredentialsForUser,
+    GetCredentialForUserV2,
+    DeleteCredentialForUser,
+    withEntityUsage,
+};

package/credential/use-cases/reauthorize-credential-for-user.js

@@ -0,0 +1,66 @@
+const Boom = require('@hapi/boom');
+
+/**
+ * Re-authorization of a credential the caller owns (Management API v2). It
+ * runs the same flow as /api/v2/authorize for the credential's entity type,
+ * with the session bound to the credential so it cannot be reused for
+ * anything else.
+ */
+async function credentialEntityType(getCredentialForUser, credentialId, user) {
+    const credential = await getCredentialForUser.execute(credentialId, user);
+    if (!credential.type) {
+        throw Boom.conflict(
+            `Credential ${credentialId} is not used by any entity, so its type is unknown; authorize a new connection instead`,
+            { code: 'CREDENTIAL_TYPE_UNKNOWN' }
+        );
+    }
+    return { entityType: credential.type, credentialId: String(credential.id) };
+}
+
+/** GET /api/v2/credentials/:credentialId/reauthorize */
+class GetCredentialReauthorization {
+    constructor({ getCredentialForUser, getAuthorizationStep }) {
+        this.getCredentialForUser = getCredentialForUser;
+        this.getAuthorizationStep = getAuthorizationStep;
+    }
+
+    async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
+        const binding = await credentialEntityType(
+            this.getCredentialForUser,
+            credentialId,
+            user
+        );
+        return this.getAuthorizationStep.execute({
+            user,
+            ...binding,
+            step,
+            sessionId,
+            state,
+        });
+    }
+}
+
+/** POST /api/v2/credentials/:credentialId/reauthorize */
+class ReauthorizeCredentialForUser {
+    constructor({ getCredentialForUser, submitAuthorizationStep }) {
+        this.getCredentialForUser = getCredentialForUser;
+        this.submitAuthorizationStep = submitAuthorizationStep;
+    }
+
+    async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
+        const binding = await credentialEntityType(
+            this.getCredentialForUser,
+            credentialId,
+            user
+        );
+        return this.submitAuthorizationStep.execute({
+            user,
+            ...binding,
+            data,
+            step,
+            sessionId,
+        });
+    }
+}
+
+module.exports = { GetCredentialReauthorization, ReauthorizeCredentialForUser };

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

@@ -25,8 +25,6 @@ async function findMany(client, collection, filter = {}, options = {}) {
     if (options.projection) command.projection = options.projection;
     if (options.sort) command.sort = options.sort;
     if (options.limit) command.limit = options.limit;
-    // The first batch holds 101 documents unless asked for more; a page wants all of its rows.
-    if (options.batchSize) command.batchSize = options.batchSize;
     const result = await client.$runCommandRaw(command);
     return result?.cursor?.firstBatch || [];
 }
@@ -60,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"**