@friggframework/core 2.0.0--canary.690.3fe2b27.0 → 2.0.0--canary.705.9cfd819.0

package/core/Worker.js

@@ -1,3 +1,4 @@
+const { SQSClient, GetQueueUrlCommand, SendMessageCommand } = require('@aws-sdk/client-sqs');
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
@@ -5,44 +6,18 @@ const { readQueueDelivery } = require('../queues/queue-delivery');
 const { runMessageScope } = require('./invocation-scope');
 const { getLogger } = require('../logs');
 
+const sqs = new SQSClient({ region: process.env.AWS_REGION });
 const log = getLogger('frigg.worker');
 
-/**
- * Worker - queue message producer/consumer base class.
- *
- * Subclass and override _run(). The queue transport is behind
- * QueueClientInterface and can be injected (friggframework/frigg#545):
- * `new MyWorker({ queueClient })`. Unlike #545 it is not required: without
- * one the worker uses an SqsQueueClient configured exactly as before
- * (AWS_REGION), created on first use rather than at module load, so
- * requiring core constructs no AWS client and a Netlify/QStash worker that
- * only calls _run() never touches SQS.
- */
 class Worker {
-    /**
-     * @param {Object} [options]
-     * @param {import('../queues/queue-client-interface').QueueClientInterface} [options.queueClient]
-     */
-    constructor(options = {}) {
-        this._queueClient = options.queueClient || null;
-    }
-
-    _getQueueClient() {
-        if (!this._queueClient) {
-            const { SqsQueueClient } = require('../queues/sqs-queue-client');
-            this._queueClient = new SqsQueueClient({
-                clientConfig: { region: process.env.AWS_REGION },
-            });
-        }
-        return this._queueClient;
-    }
-
     async getQueueURL(params) {
         // Passing params in because there will be multiple QueueNames
         // let params = {
         //     QueueName:  process.env.QueueName
         // };
-        return this._getQueueClient().getQueueUrl(params);
+        const command = new GetQueueUrlCommand(params);
+        const data = await sqs.send(command);
+        return data.QueueUrl;
     }
 
     async run(params, context = {}) {
@@ -116,7 +91,8 @@ class Worker {
     }
 
     async sendAsyncSQSMessage(params) {
-        const data = await this._getQueueClient().sendMessage(params);
+        const command = new SendMessageCommand(params);
+        const data = await sqs.send(command);
         return data.MessageId;
     }
 

package/core/create-handler.js

@@ -81,15 +81,6 @@ const createHandler = (optionByName = {}) => {
                     if (shouldUseDatabase) {
                         const { connectPrisma } = require('../database/prisma');
                         await connectPrisma();
-
-                        // Extension bootstraps (e.g. db-credentials swapping a
-                        // module's env for its DB loader) run once per
-                        // process, after the connect and before any request
-                        // builds a module. AWS and Netlify both reach here.
-                        const {
-                            initializeApp,
-                        } = require('../extensions/initialize-app');
-                        await initializeApp();
                     }
 
                     // Helps reuse the database connection.  Lowers response times.

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

@@ -186,40 +186,6 @@ 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,21 +80,6 @@ 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,29 +188,6 @@ 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,34 +205,6 @@ 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/database/config.js

@@ -3,39 +3,6 @@
  * Manages configuration for Prisma ORM operations
  */
 
-/**
- * Maps an app definition's `database` block to a Prisma database type.
- *
- * @param {Object|undefined} database - `Definition.database`
- * @param {string} where - where the definition lives, for the error message
- * @returns {'mongodb'|'postgresql'|'documentdb'}
- */
-function databaseTypeFromConfig(database, where) {
-    if (!database) {
-        throw new Error(
-            '[Frigg] App definition missing database configuration. ' +
-            `Add database: { postgres: { enable: true } } (or mongoDB/documentDB) to ${where}`
-        );
-    }
-
-    // Determine database type from enabled database
-    // Priority order: postgres > mongoDB > documentDB
-    if (database.postgres?.enable === true) {
-        return 'postgresql';
-    }
-    if (database.mongoDB?.enable === true) {
-        return 'mongodb';
-    }
-    if (database.documentDB?.enable === true) {
-        return 'documentdb';
-    }
-
-    throw new Error(
-        '[Frigg] No database enabled in app definition. ' +
-        'Set one of: database.postgres.enable, database.mongoDB.enable, or database.documentDB.enable to true'
-    );
-}
-
 /**
  * Determines database type from environment or app definition
  * 
@@ -54,20 +21,6 @@ function getDatabaseType() {
 
     // Fallback: Load app definition
     try {
-        // A definition preset with setAppDefinition() (provider-netlify's
-        // function preamble) wins: on Netlify process.cwd() is the function
-        // root at runtime, so discovery cannot find the backend.
-        const {
-            getPresetAppDefinition,
-        } = require('../handlers/app-definition-loader');
-        const preset = getPresetAppDefinition();
-        if (preset) {
-            return databaseTypeFromConfig(
-                preset.database,
-                'your backend/index.js'
-            );
-        }
-
         const path = require('node:path');
         const fs = require('node:fs');
         const { findNearestBackendPackageJson } = require('../utils');
@@ -123,7 +76,30 @@ function getDatabaseType() {
         }
 
         database = backendModule?.Definition?.database;
-        return databaseTypeFromConfig(database, backendIndexPath);
+
+        if (!database) {
+            throw new Error(
+                '[Frigg] App definition missing database configuration. ' +
+                `Add database: { postgres: { enable: true } } (or mongoDB/documentDB) to ${backendIndexPath}`
+            );
+        }
+
+        // Determine database type from enabled database
+        // Priority order: postgres > mongoDB > documentDB
+        if (database.postgres?.enable === true) {
+            return 'postgresql';
+        }
+        if (database.mongoDB?.enable === true) {
+            return 'mongodb';
+        }
+        if (database.documentDB?.enable === true) {
+            return 'documentdb';
+        }
+
+        throw new Error(
+            '[Frigg] No database enabled in app definition. ' +
+            'Set one of: database.postgres.enable, database.mongoDB.enable, or database.documentDB.enable to true'
+        );
     } catch (error) {
         // Re-throw with context if it's our error
         if (error.message.includes('[Frigg]')) {

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/documentdb-utils.js

@@ -58,8 +58,6 @@ async function insertOne(client, collection, document) {
 
         // Provide helpful context for common errors
         if (error.code === 11000) {
-            // `code` lets callers recognise a lost race without parsing text
-            // (see database/unique-violation.js).
             throw Object.assign(
                 new Error(`${errorMsg} - Duplicate key violation`),
                 { code: 11000 }

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_`) 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.
+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
 
@@ -456,8 +428,6 @@ 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)
@@ -583,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)
 
@@ -645,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"
 }
 ```
 
@@ -779,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:**
@@ -797,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_*`, 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
+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