@friggframework/core 2.0.0--canary.545.1176a00.0 → 2.0.0--canary.545.29ef032.0

package/core/Worker.js

@@ -1,23 +1,41 @@
-const {
-    SQSClient,
-    GetQueueUrlCommand,
-    SendMessageCommand,
-} = require('@aws-sdk/client-sqs');
 const _ = require('lodash');
 const { RequiredPropertyError } = require('../errors');
 const { get } = require('../assertions');
 
-const sqs = new SQSClient({ region: process.env.AWS_REGION });
-
+/**
+ * Worker - Queue message producer/consumer base class.
+ *
+ * Subclass and override _run() to implement your worker logic.
+ * The queue transport (SQS, Netlify, etc.) is abstracted behind
+ * QueueClientInterface, injected via constructor options.
+ *
+ * BREAKING CHANGE (v3): A queueClient must be explicitly provided.
+ * For AWS/SQS, pass `new SqsQueueClient()` from @friggframework/provider-aws.
+ * See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.
+ */
 class Worker {
+    constructor(options = {}) {
+        this._queueClient = options.queueClient || null;
+    }
+
+    /**
+     * Get the queue client. Throws if none was injected.
+     * @returns {QueueClientInterface}
+     */
+    _getQueueClient() {
+        if (!this._queueClient) {
+            throw new Error(
+                'Worker requires a queueClient. Pass one via constructor options, e.g.:\n' +
+                '  const { SqsQueueClient } = require("@friggframework/provider-aws");\n' +
+                '  new MyWorker({ queueClient: new SqsQueueClient() })\n' +
+                'See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.'
+            );
+        }
+        return this._queueClient;
+    }
+
     async getQueueURL(params) {
-        // Passing params in because there will be multiple QueueNames
-        // let params = {
-        //     QueueName:  process.env.QueueName
-        // };
-        const command = new GetQueueUrlCommand(params);
-        const data = await sqs.send(command);
-        return data.QueueUrl;
+        return this._getQueueClient().getQueueUrl(params);
     }
 
     async run(params, context = {}) {
@@ -51,8 +69,7 @@ class Worker {
     }
 
     async sendAsyncSQSMessage(params) {
-        const command = new SendMessageCommand(params);
-        const data = await sqs.send(command);
+        const data = await this._getQueueClient().sendMessage(params);
         return data.MessageId;
     }
 

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

@@ -170,7 +170,7 @@ function loadModuleEncryptionSchemas(integrations) {
 
     const {
         getModulesDefinitionFromIntegrationClasses,
-    } = require('../integrations/utils/map-integration-dto');
+    } = require('../../integrations/utils/map-integration-dto');
 
     const moduleDefinitions =
         getModulesDefinitionFromIntegrationClasses(integrations);

package/database/models/WebsocketConnection.js

@@ -1,13 +1,31 @@
+/**
+ * WebsocketConnection Mongoose Model
+ *
+ * BREAKING CHANGE (v3): Call WebsocketConnection.setMessageSender() before
+ * using getActiveConnections(). For AWS API Gateway, pass
+ * `new ApiGatewayMessageSender()` from @friggframework/provider-aws.
+ * See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.
+ */
 const { mongoose } = require('../mongoose');
 const {
-    ApiGatewayManagementApiClient,
-    PostToConnectionCommand,
-} = require('@aws-sdk/client-apigatewaymanagementapi');
+    StaleConnectionError,
+} = require('../../websocket/websocket-message-sender-interface');
+
+let _messageSender = null;
 
 const schema = new mongoose.Schema({
     connectionId: { type: mongoose.Schema.Types.String },
 });
 
+/**
+ * Set the message sender for WebSocket send functionality.
+ * Must be called before getActiveConnections().
+ * @param {WebSocketMessageSenderInterface} sender
+ */
+schema.statics.setMessageSender = function (sender) {
+    _messageSender = sender;
+};
+
 // Add a static method to get active connections
 schema.statics.getActiveConnections = async function () {
     try {
@@ -16,25 +34,28 @@ schema.statics.getActiveConnections = async function () {
             return [];
         }
 
+        if (!_messageSender) {
+            throw new Error(
+                'WebsocketConnection requires a message sender. Call WebsocketConnection.setMessageSender() first, e.g.:\n' +
+                '  const { ApiGatewayMessageSender } = require("@friggframework/provider-aws");\n' +
+                '  WebsocketConnection.setMessageSender(new ApiGatewayMessageSender());\n' +
+                'See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.'
+            );
+        }
+
+        const sender = _messageSender;
         const connections = await this.find({}, 'connectionId');
         return connections.map((conn) => ({
             connectionId: conn.connectionId,
             send: async (data) => {
-                const apigwManagementApi = new ApiGatewayManagementApiClient({
-                    endpoint: process.env.WEBSOCKET_API_ENDPOINT,
-                });
-
                 try {
-                    const command = new PostToConnectionCommand({
-                        ConnectionId: conn.connectionId,
-                        Data: JSON.stringify(data),
-                    });
-                    await apigwManagementApi.send(command);
+                    await sender.send(
+                        conn.connectionId,
+                        data,
+                        process.env.WEBSOCKET_API_ENDPOINT
+                    );
                 } catch (error) {
-                    if (
-                        error.statusCode === 410 ||
-                        error.$metadata?.httpStatusCode === 410
-                    ) {
+                    if (error instanceof StaleConnectionError) {
                         console.log(`Stale connection ${conn.connectionId}`);
                         await this.deleteOne({
                             connectionId: conn.connectionId,

package/encrypt/Cryptor.js

@@ -1,64 +1,75 @@
 /**
  * Cryptor - Encryption Service Adapter
  *
- * Infrastructure Layer adapter for AWS KMS and local AES encryption.
- * Provides envelope encryption pattern for field-level encryption.
+ * Infrastructure Layer adapter for envelope encryption.
+ * Key management is delegated to an EncryptionKeyProviderInterface adapter:
+ * - KmsEncryptionKeyProvider (in @friggframework/provider-aws) for AWS KMS
+ * - AesEncryptionKeyProvider (in core) for local AES keys
  *
  * Envelope Encryption Pattern:
- * 1. Generate Data Encryption Key (DEK) via KMS or locally
+ * 1. Generate Data Encryption Key (DEK) via key provider
  * 2. Encrypt field value with DEK using AES-256-CTR
- * 3. Encrypt DEK with Master Key (KMS CMK or AES_KEY)
+ * 3. Store encrypted DEK alongside ciphertext
  * 4. Return format: "keyId:encryptedText:encryptedKey"
  *
- * Benefits:
- * - Reduces KMS API calls (unique DEK per operation)
- * - Master key never leaves KMS
- * - Enables key rotation without re-encrypting data
+ * BREAKING CHANGE (v3): A keyProvider must be explicitly provided,
+ * or pass { shouldUseAws: false } to auto-create AesEncryptionKeyProvider.
+ * For AWS KMS, pass `new KmsEncryptionKeyProvider()` from @friggframework/provider-aws.
+ * See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.
  */
 
-const crypto = require('crypto');
-const {
-    KMSClient,
-    GenerateDataKeyCommand,
-    DecryptCommand,
-} = require('@aws-sdk/client-kms');
 const aes = require('./aes');
 
 class Cryptor {
-    constructor({ shouldUseAws }) {
-        this.shouldUseAws = shouldUseAws;
-    }
-
-    async generateDataKey() {
-        if (this.shouldUseAws) {
-            const kmsClient = new KMSClient({});
-            const command = new GenerateDataKeyCommand({
-                KeyId: process.env.KMS_KEY_ARN,
-                KeySpec: 'AES_256',
-            });
-            const dataKey = await kmsClient.send(command);
-
-            const keyId = Buffer.from(dataKey.KeyId).toString('base64');
-            const encryptedKey = Buffer.from(dataKey.CiphertextBlob).toString(
-                'base64'
+    /**
+     * @param {Object} options
+     * @param {boolean} [options.shouldUseAws] - true requires explicit keyProvider; false auto-creates AesEncryptionKeyProvider
+     * @param {EncryptionKeyProviderInterface} [options.keyProvider] - Explicit key provider (takes precedence)
+     */
+    constructor({ shouldUseAws, keyProvider } = {}) {
+        if (keyProvider) {
+            this._keyProvider = keyProvider;
+        } else if (shouldUseAws) {
+            throw new Error(
+                'Cryptor with shouldUseAws=true requires an explicit keyProvider. Pass one via constructor options, e.g.:\n' +
+                '  const { KmsEncryptionKeyProvider } = require("@friggframework/provider-aws");\n' +
+                '  new Cryptor({ shouldUseAws: true, keyProvider: new KmsEncryptionKeyProvider() })\n' +
+                'See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.'
             );
-            const plaintext = dataKey.Plaintext;
-            return { keyId, encryptedKey, plaintext };
+        } else {
+            // AES mode — no AWS dependency needed
+            const { AesEncryptionKeyProvider } = require('./aes-encryption-key-provider');
+            this._keyProvider = new AesEncryptionKeyProvider();
         }
+        this._shouldUseAws = shouldUseAws;
+    }
 
-        const { AES_KEY, AES_KEY_ID } = process.env;
-        const randomKey = crypto.randomBytes(32).toString('hex').slice(0, 32);
+    /**
+     * Get the key provider.
+     * @returns {EncryptionKeyProviderInterface}
+     */
+    _getKeyProvider() {
+        return this._keyProvider;
+    }
 
-        return {
-            keyId: Buffer.from(AES_KEY_ID).toString('base64'),
-            encryptedKey: Buffer.from(aes.encrypt(randomKey, AES_KEY)).toString(
-                'base64'
-            ),
-            plaintext: randomKey,
-        };
+    async generateDataKey() {
+        return this._getKeyProvider().generateDataKey();
     }
 
+    /**
+     * Look up an AES key by identifier from environment variables.
+     * Kept for backward compatibility.
+     *
+     * @param {string} keyId - Key identifier
+     * @returns {string} The master key
+     */
     getKeyFromEnvironment(keyId) {
+        const provider = this._getKeyProvider();
+        if (typeof provider.getKeyFromEnvironment === 'function') {
+            return provider.getKeyFromEnvironment(keyId);
+        }
+
+        // Fallback for providers that don't implement getKeyFromEnvironment
         const availableKeys = {
             [process.env.AES_KEY_ID]: process.env.AES_KEY,
             [process.env.DEPRECATED_AES_KEY_ID]: process.env.DEPRECATED_AES_KEY,
@@ -74,19 +85,7 @@ class Cryptor {
     }
 
     async decryptDataKey(keyId, encryptedKey) {
-        if (this.shouldUseAws) {
-            const kmsClient = new KMSClient({});
-            const command = new DecryptCommand({
-                KeyId: keyId,
-                CiphertextBlob: encryptedKey,
-            });
-            const dataKey = await kmsClient.send(command);
-
-            return dataKey.Plaintext;
-        }
-
-        const key = this.getKeyFromEnvironment(keyId);
-        return aes.decrypt(encryptedKey, key);
+        return this._getKeyProvider().decryptDataKey(keyId, encryptedKey);
     }
 
     async encrypt(text) {

package/encrypt/aes-encryption-key-provider.js

@@ -0,0 +1,82 @@
+/**
+ * AES Encryption Key Provider (Adapter)
+ *
+ * Local AES-based implementation of EncryptionKeyProviderInterface.
+ * Uses environment-variable-based master keys for envelope encryption.
+ *
+ * No external dependencies — works on any platform.
+ *
+ * Environment Variables:
+ * - AES_KEY_ID: Identifier for the current AES master key
+ * - AES_KEY: The current AES master key (32 chars)
+ * - DEPRECATED_AES_KEY_ID: (optional) Previous key ID for key rotation
+ * - DEPRECATED_AES_KEY: (optional) Previous key for decrypting old data
+ */
+
+const crypto = require('crypto');
+const aes = require('./aes');
+const {
+    EncryptionKeyProviderInterface,
+} = require('./encryption-key-provider-interface');
+
+class AesEncryptionKeyProvider extends EncryptionKeyProviderInterface {
+    /**
+     * Generate a data encryption key using local AES
+     *
+     * Creates a random DEK and encrypts it with the AES master key
+     * from environment variables.
+     *
+     * @returns {Promise<{keyId: string, encryptedKey: string, plaintext: string}>}
+     */
+    async generateDataKey() {
+        const { AES_KEY, AES_KEY_ID } = process.env;
+        const randomKey = crypto.randomBytes(32).toString('hex').slice(0, 32);
+
+        return {
+            keyId: Buffer.from(AES_KEY_ID).toString('base64'),
+            encryptedKey: Buffer.from(aes.encrypt(randomKey, AES_KEY)).toString(
+                'base64'
+            ),
+            plaintext: randomKey,
+        };
+    }
+
+    /**
+     * Decrypt a data encryption key using the AES master key
+     *
+     * Looks up the master key by keyId from environment variables,
+     * supporting key rotation via DEPRECATED_AES_KEY.
+     *
+     * @param {string} keyId - Key identifier to look up in environment
+     * @param {string|Buffer} encryptedKey - Encrypted DEK to decrypt
+     * @returns {Promise<string>} Decrypted plaintext DEK
+     */
+    async decryptDataKey(keyId, encryptedKey) {
+        const key = this.getKeyFromEnvironment(keyId);
+        return aes.decrypt(encryptedKey, key);
+    }
+
+    /**
+     * Look up an AES master key by its identifier
+     *
+     * @param {string} keyId - Key identifier
+     * @returns {string} The master key
+     * @throws {Error} If key not found in environment
+     */
+    getKeyFromEnvironment(keyId) {
+        const availableKeys = {
+            [process.env.AES_KEY_ID]: process.env.AES_KEY,
+            [process.env.DEPRECATED_AES_KEY_ID]: process.env.DEPRECATED_AES_KEY,
+        };
+
+        const key = availableKeys[keyId];
+
+        if (!key) {
+            throw new Error('Encryption key not found');
+        }
+
+        return key;
+    }
+}
+
+module.exports = { AesEncryptionKeyProvider };

package/encrypt/encryption-key-provider-interface.js

@@ -0,0 +1,50 @@
+/**
+ * Encryption Key Provider Interface (Port)
+ *
+ * Defines the contract for envelope encryption key operations.
+ * Used by Cryptor for generating and decrypting data encryption keys.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS KMS, local AES, Vault, etc.)
+ *
+ * Envelope Encryption Pattern:
+ * 1. generateDataKey() creates a fresh DEK (plaintext + encrypted form)
+ * 2. Caller encrypts data with the plaintext DEK
+ * 3. Caller stores the encrypted DEK alongside the ciphertext
+ * 4. decryptDataKey() recovers the plaintext DEK from the encrypted form
+ * 5. Caller decrypts data with the recovered DEK
+ */
+class EncryptionKeyProviderInterface {
+    /**
+     * Generate a new data encryption key
+     *
+     * Returns both the plaintext key (for immediate encryption) and an
+     * encrypted copy (for storage alongside the ciphertext).
+     *
+     * @returns {Promise<{keyId: string, encryptedKey: string, plaintext: string|Buffer}>}
+     *   - keyId: Base64-encoded identifier for the master key used
+     *   - encryptedKey: Base64-encoded encrypted copy of the DEK
+     *   - plaintext: The raw DEK (string or Buffer) for immediate use
+     */
+    async generateDataKey() {
+        throw new Error(
+            'Method generateDataKey must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Decrypt a previously encrypted data encryption key
+     *
+     * @param {string} keyId - Identifier of the master key used for encryption
+     * @param {string|Buffer} encryptedKey - The encrypted DEK to decrypt
+     * @returns {Promise<string|Buffer>} The decrypted plaintext DEK
+     */
+    async decryptDataKey(keyId, encryptedKey) {
+        throw new Error(
+            'Method decryptDataKey must be implemented by subclass'
+        );
+    }
+}
+
+module.exports = { EncryptionKeyProviderInterface };

package/handlers/routers/db-migration.js

@@ -21,9 +21,10 @@
 const { Router } = require('express');
 const catchAsyncError = require('express-async-handler');
 const { validateAdminApiKey } = require('../middleware/admin-auth');
-const {
-    MigrationStatusRepositoryS3,
-} = require('../../database/repositories/migration-status-repository-s3');
+// Lazy-loaded from provider-aws to avoid pulling in @aws-sdk/client-s3 on non-AWS platforms
+function getMigrationStatusRepositoryS3() {
+    return require('@friggframework/provider-aws').MigrationStatusRepositoryS3;
+}
 const {
     TriggerDatabaseMigrationUseCase,
     ValidationError: TriggerValidationError,
@@ -33,39 +34,61 @@ const {
     ValidationError: GetValidationError,
     NotFoundError,
 } = require('../../database/use-cases/get-migration-status-use-case');
-const { LambdaInvoker } = require('../../database/adapters/lambda-invoker');
+// Lazy-loaded from provider-aws to avoid pulling in @aws-sdk/client-lambda on non-AWS platforms
+function getLambdaInvoker() {
+    return require('@friggframework/provider-aws').LambdaInvoker;
+}
 const {
     GetDatabaseStateViaWorkerUseCase,
 } = require('../../database/use-cases/get-database-state-via-worker-use-case');
 
 const router = Router();
 
-// Dependency injection
-// Use S3 repository to avoid User table dependency (chicken-and-egg problem)
-const bucketName =
-    process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
-const migrationStatusRepository = new MigrationStatusRepositoryS3(bucketName);
-
-const triggerMigrationUseCase = new TriggerDatabaseMigrationUseCase({
-    migrationStatusRepository,
-    // Note: QueuerUtil is used directly in the use case (static utility)
-});
-const getStatusUseCase = new GetMigrationStatusUseCase({
-    migrationStatusRepository,
-});
-
-// Lambda invocation for database state check (keeps router lightweight)
-const lambdaInvoker = new LambdaInvoker();
-const workerFunctionName =
-    process.env.WORKER_FUNCTION_NAME ||
-    `${process.env.SERVICE || 'unknown'}-${
-        process.env.STAGE || 'production'
-    }-dbMigrationWorker`;
-
-const getDatabaseStateUseCase = new GetDatabaseStateViaWorkerUseCase({
-    lambdaInvoker,
-    workerFunctionName,
-});
+// Dependency injection — lazy-initialized on first request to avoid
+// pulling in AWS SDKs at module load time on non-AWS platforms.
+let _migrationStatusRepository = null;
+let _triggerMigrationUseCase = null;
+let _getStatusUseCase = null;
+let _lambdaInvoker = null;
+
+function getMigrationDeps() {
+    if (!_migrationStatusRepository) {
+        const MigrationStatusRepositoryS3 = getMigrationStatusRepositoryS3();
+        const bucketName =
+            process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
+        _migrationStatusRepository = new MigrationStatusRepositoryS3(bucketName);
+        _triggerMigrationUseCase = new TriggerDatabaseMigrationUseCase({
+            migrationStatusRepository: _migrationStatusRepository,
+        });
+        _getStatusUseCase = new GetMigrationStatusUseCase({
+            migrationStatusRepository: _migrationStatusRepository,
+        });
+        const LambdaInvoker = getLambdaInvoker();
+        _lambdaInvoker = new LambdaInvoker();
+    }
+    return {
+        migrationStatusRepository: _migrationStatusRepository,
+        triggerMigrationUseCase: _triggerMigrationUseCase,
+        getStatusUseCase: _getStatusUseCase,
+        lambdaInvoker: _lambdaInvoker,
+    };
+}
+let _getDatabaseStateUseCase = null;
+function getDatabaseStateUseCaseInstance() {
+    if (!_getDatabaseStateUseCase) {
+        const { lambdaInvoker } = getMigrationDeps();
+        const workerFunctionName =
+            process.env.WORKER_FUNCTION_NAME ||
+            `${process.env.SERVICE || 'unknown'}-${
+                process.env.STAGE || 'production'
+            }-dbMigrationWorker`;
+        _getDatabaseStateUseCase = new GetDatabaseStateViaWorkerUseCase({
+            lambdaInvoker,
+            workerFunctionName,
+        });
+    }
+    return _getDatabaseStateUseCase;
+}
 
 // Apply admin API key validation to all routes (shared middleware)
 router.use(validateAdminApiKey);
@@ -106,7 +129,7 @@ router.post(
         );
 
         try {
-            const result = await triggerMigrationUseCase.execute({
+            const result = await getMigrationDeps().triggerMigrationUseCase.execute({
                 userId,
                 dbType,
                 stage,
@@ -153,12 +176,12 @@ router.get(
         const stage = req.query.stage || process.env.STAGE || 'production';
 
         console.log(
-            `Checking database state: stage=${stage}, worker=${workerFunctionName}`
+            `Checking database state: stage=${stage}`
         );
 
         try {
             // Invoke worker Lambda to check database state
-            const status = await getDatabaseStateUseCase.execute(stage);
+            const status = await getDatabaseStateUseCaseInstance().execute(stage);
 
             res.status(200).json(status);
         } catch (error) {
@@ -210,7 +233,7 @@ router.get(
         );
 
         try {
-            const status = await getStatusUseCase.execute(migrationId, stage);
+            const status = await getMigrationDeps().getStatusUseCase.execute(migrationId, stage);
 
             res.status(200).json(status);
         } catch (error) {