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

package/handlers/routers/health.js

@@ -93,257 +93,30 @@ const validateApiKey = (req, res, next) => {
 
 router.use(validateApiKey);
 
-// Helper to detect VPC configuration
-const detectVpcConfiguration = async () => {
-    const results = {
-        isInVpc: false,
-        hasInternetAccess: false,
-        canResolvePublicDns: false,
-        canConnectToAws: false,
-        vpcEndpoints: [],
-    };
-
+// AWS-specific health checks (VPC, KMS) are lazy-loaded from provider-aws
+// to avoid pulling in @aws-sdk on non-AWS platforms.
+function getAwsHealthChecks() {
     try {
-        // Check if we're in a VPC by looking for VPC-specific environment
-        // Lambda in VPC has specific network interface configuration
-        const dns = require('dns').promises;
-
-        // Test 1: Can we resolve public DNS? (indicates DNS configuration)
-        try {
-            await Promise.race([
-                dns.resolve4('www.google.com'),
-                new Promise((_, reject) =>
-                    setTimeout(() => reject(new Error('timeout')), 2000)
-                ),
-            ]);
-            results.canResolvePublicDns = true;
-        } catch (e) {
-            console.log('Public DNS resolution failed:', e.message);
-        }
-
-        // Test 2: Can we reach internet? (indicates NAT gateway)
-        try {
-            const https = require('https');
-            await new Promise((resolve, reject) => {
-                const req = https.get(
-                    'https://www.google.com',
-                    { timeout: 2000 },
-                    (res) => {
-                        res.destroy();
-                        resolve(true);
-                    }
-                );
-                req.on('error', reject);
-                req.on('timeout', () => {
-                    req.destroy();
-                    reject(new Error('timeout'));
-                });
-            });
-            results.hasInternetAccess = true;
-        } catch (e) {
-            console.log('Internet connectivity test failed:', e.message);
-        }
-
-        // Test 3: Check for VPC endpoints by trying to resolve internal AWS endpoints
-        const region = process.env.AWS_REGION; // Lambda always provides this
-        const vpcEndpointDomains = [
-            `com.amazonaws.${region}.kms`,
-            `com.amazonaws.vpce.${region}`,
-            `kms.${region}.amazonaws.com`,
-        ];
-
-        for (const domain of vpcEndpointDomains) {
-            try {
-                const addresses = await Promise.race([
-                    dns.resolve4(domain).catch(() => dns.resolve6(domain)),
-                    new Promise((_, reject) =>
-                        setTimeout(() => reject(new Error('timeout')), 1000)
-                    ),
-                ]);
-                if (addresses && addresses.length > 0) {
-                    // Check if it's a private IP (VPC endpoint indicator)
-                    const isPrivateIp = addresses.some(
-                        (ip) =>
-                            ip.startsWith('10.') ||
-                            ip.startsWith('172.') ||
-                            ip.startsWith('192.168.')
-                    );
-                    if (isPrivateIp) {
-                        results.vpcEndpoints.push(domain);
-                    }
-                }
-            } catch (e) {
-                // Expected for non-existent endpoints
-            }
-        }
-
-        // Check if Lambda is in VPC using VPC_ENABLED env var set by infrastructure
-        results.isInVpc =
-            process.env.VPC_ENABLED === 'true' ||
-            (!results.hasInternetAccess && results.canResolvePublicDns) ||
-            results.vpcEndpoints.length > 0;
-
-        results.canConnectToAws =
-            results.hasInternetAccess || results.vpcEndpoints.length > 0;
-    } catch (error) {
-        console.error('VPC detection error:', error.message);
+        return require('@friggframework/provider-aws/health/kms-health-check');
+    } catch {
+        return null;
     }
+}
 
-    return results;
-};
-
-// KMS decrypt capability check
 const checkKmsDecryptCapability = async () => {
-    const start = Date.now();
-    const { KMS_KEY_ARN } = process.env;
-    if (!KMS_KEY_ARN) {
-        return {
-            status: 'skipped',
-            reason: 'KMS_KEY_ARN not configured',
-        };
+    const awsHealth = getAwsHealthChecks();
+    if (!awsHealth) {
+        return { status: 'skipped', reason: 'AWS provider not available' };
     }
+    return awsHealth.checkKmsDecryptCapability();
+};
 
-    // Log environment for debugging
-    console.log('KMS Check Debug:', {
-        hasKmsKeyArn: !!KMS_KEY_ARN,
-        kmsKeyArnPrefix: KMS_KEY_ARN?.substring(0, 30),
-        awsRegion: process.env.AWS_REGION,
-        hasDiscoveryKey: !!process.env.AWS_DISCOVERY_KMS_KEY_ID,
-    });
-
-    // First, detect VPC configuration
-    const vpcConfig = await detectVpcConfiguration();
-    console.log('VPC Configuration:', vpcConfig);
-
-    // Test DNS resolution for KMS endpoint
-    try {
-        const dns = require('dns').promises;
-        const region = process.env.AWS_REGION; // Lambda always provides this
-        const kmsEndpoint = `kms.${region}.amazonaws.com`;
-        console.log('Testing DNS resolution for:', kmsEndpoint);
-
-        // Wrap DNS resolution in a timeout
-        const dnsPromise = dns.resolve4(kmsEndpoint);
-        const timeoutPromise = new Promise((_, reject) =>
-            setTimeout(() => reject(new Error('DNS resolution timeout')), 3000)
-        );
-
-        const addresses = await Promise.race([dnsPromise, timeoutPromise]);
-        console.log('KMS endpoint resolved to:', addresses);
-
-        // Check if resolved to private IP (VPC endpoint)
-        const isVpcEndpoint = addresses.some(
-            (ip) =>
-                ip.startsWith('10.') ||
-                ip.startsWith('172.') ||
-                ip.startsWith('192.168.')
-        );
-
-        if (isVpcEndpoint) {
-            console.log(
-                'KMS VPC Endpoint detected - using private connectivity'
-            );
-        }
-
-        // Test TCP connectivity to KMS (port 443)
-        const net = require('net');
-        const testConnection = () =>
-            new Promise((resolve) => {
-                const socket = new net.Socket();
-                const connectionTimeout = setTimeout(() => {
-                    socket.destroy();
-                    resolve({ connected: false, error: 'Connection timeout' });
-                }, 3000);
-
-                socket.on('connect', () => {
-                    clearTimeout(connectionTimeout);
-                    socket.destroy();
-                    resolve({ connected: true });
-                });
-
-                socket.on('error', (err) => {
-                    clearTimeout(connectionTimeout);
-                    resolve({ connected: false, error: err.message });
-                });
-
-                // Try connecting to first resolved address on HTTPS port
-                socket.connect(443, addresses[0]);
-            });
-
-        const connResult = await testConnection();
-        console.log('TCP connectivity test:', connResult);
-
-        if (!connResult.connected) {
-            return {
-                status: 'unhealthy',
-                error: `Cannot connect to KMS endpoint: ${connResult.error}`,
-                dnsResolved: true,
-                tcpConnection: false,
-                vpcConfig,
-                latencyMs: Date.now() - start,
-            };
-        }
-    } catch (dnsError) {
-        console.error('DNS resolution failed:', dnsError.message);
-        return {
-            status: 'unhealthy',
-            error: `Cannot resolve KMS endpoint: ${dnsError.message}`,
-            dnsResolved: false,
-            vpcConfig,
-            latencyMs: Date.now() - start,
-        };
-    }
-
-    try {
-        // Use AWS SDK v3 for consistency with the rest of the codebase
-        // eslint-disable-next-line global-require
-        const {
-            KMSClient,
-            GenerateDataKeyCommand,
-            DecryptCommand,
-        } = require('@aws-sdk/client-kms');
-
-        // Lambda always provides AWS_REGION
-        const region = process.env.AWS_REGION;
-
-        const kms = new KMSClient({
-            region,
-            requestHandler: {
-                connectionTimeout: 10000, // 10 second connection timeout
-                requestTimeout: 25000, // 25 second timeout for slow VPC connections
-            },
-            maxAttempts: 1, // No retries on health checks
-        });
-
-        // Generate a data key (without plaintext logging) then immediately decrypt ciphertext to ensure decrypt perms.
-        const dataKeyResp = await kms.send(
-            new GenerateDataKeyCommand({
-                KeyId: KMS_KEY_ARN,
-                KeySpec: 'AES_256',
-            })
-        );
-        const decryptResp = await kms.send(
-            new DecryptCommand({ CiphertextBlob: dataKeyResp.CiphertextBlob })
-        );
-
-        const success = Boolean(
-            dataKeyResp.CiphertextBlob && decryptResp.Plaintext
-        );
-
-        return {
-            status: success ? 'healthy' : 'unhealthy',
-            kmsKeyArnSuffix: KMS_KEY_ARN.slice(-12),
-            vpcConfig,
-            latencyMs: Date.now() - start,
-        };
-    } catch (error) {
-        return {
-            status: 'unhealthy',
-            error: error.message,
-            vpcConfig,
-            latencyMs: Date.now() - start,
-        };
+const detectVpcConfiguration = async () => {
+    const awsHealth = getAwsHealthChecks();
+    if (!awsHealth) {
+        return { status: 'skipped', reason: 'AWS provider not available' };
     }
+    return awsHealth.detectVpcConfiguration();
 };
 
 router.get('/health', async (_req, res) => {

package/handlers/workers/db-migration.js

@@ -49,17 +49,21 @@ const {
 const {
     CheckDatabaseStateUseCase,
 } = require('../../database/use-cases/check-database-state-use-case');
-const {
-    MigrationStatusRepositoryS3,
-} = require('../../database/repositories/migration-status-repository-s3');
-
 // Inject prisma-runner as dependency
 const prismaRunner = require('../../database/utils/prisma-runner');
 
-// Use S3 repository for migration status tracking (no User table dependency)
-const bucketName =
-    process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
-const migrationStatusRepository = new MigrationStatusRepositoryS3(bucketName);
+// S3 repository is lazy-loaded from provider-aws to avoid pulling in
+// @aws-sdk/client-s3 on non-AWS platforms.
+let _migrationStatusRepository = null;
+function getMigrationStatusRepository() {
+    if (!_migrationStatusRepository) {
+        const { MigrationStatusRepositoryS3 } = require('@friggframework/provider-aws');
+        const bucketName =
+            process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
+        _migrationStatusRepository = new MigrationStatusRepositoryS3(bucketName);
+    }
+    return _migrationStatusRepository;
+}
 
 /**
  * Sanitizes error messages to prevent credential leaks
@@ -238,7 +242,7 @@ exports.handler = async (event, context) => {
             console.log(
                 `\n✓ Updating migration status to RUNNING: ${migrationId}`
             );
-            await migrationStatusRepository.update({
+            await getMigrationStatusRepository().update({
                 migrationId,
                 stage,
                 state: 'RUNNING',
@@ -278,7 +282,7 @@ exports.handler = async (event, context) => {
             console.log(
                 `\n✓ Updating migration status to COMPLETED: ${migrationId}`
             );
-            await migrationStatusRepository.update({
+            await getMigrationStatusRepository().update({
                 migrationId,
                 stage,
                 state: 'COMPLETED',
@@ -341,7 +345,7 @@ exports.handler = async (event, context) => {
                 console.log(
                     `\n✓ Updating migration status to FAILED: ${migrationId}`
                 );
-                await migrationStatusRepository.update({
+                await getMigrationStatusRepository().update({
                     migrationId,
                     stage,
                     state: 'FAILED',

package/index.js

@@ -95,10 +95,22 @@ const utils = require('./utils');
 const {
     QueuerUtil,
     QueueProvider,
+    QueueClientInterface,
     createQueueProvider,
     QUEUE_PROVIDERS,
 } = require('./queues');
 
+const {
+    EncryptionKeyProviderInterface,
+} = require('./encrypt/encryption-key-provider-interface');
+const {
+    AesEncryptionKeyProvider,
+} = require('./encrypt/aes-encryption-key-provider');
+const {
+    WebSocketMessageSenderInterface,
+    StaleConnectionError,
+} = require('./websocket/websocket-message-sender-interface');
+
 const {
     resolveProvider,
     determineProviderName,
@@ -200,9 +212,18 @@ module.exports = {
     // queues
     QueuerUtil,
     QueueProvider,
+    QueueClientInterface,
     createQueueProvider,
     QUEUE_PROVIDERS,
 
+    // encryption interfaces
+    EncryptionKeyProviderInterface,
+    AesEncryptionKeyProvider,
+
+    // websocket interfaces
+    WebSocketMessageSenderInterface,
+    StaleConnectionError,
+
     // providers
     resolveProvider,
     determineProviderName,

package/infrastructure/scheduler/index.js

@@ -28,7 +28,7 @@ module.exports = {
 
     // Adapters — lazy to avoid eager require of @aws-sdk/client-scheduler
     get EventBridgeSchedulerAdapter() {
-        return require('./eventbridge-scheduler-adapter').EventBridgeSchedulerAdapter;
+        return require('@friggframework/provider-aws').EventBridgeSchedulerAdapter;
     },
     get MockSchedulerAdapter() {
         return require('./mock-scheduler-adapter').MockSchedulerAdapter;

package/infrastructure/scheduler/scheduler-service-factory.js

@@ -57,7 +57,7 @@ function createSchedulerService(options = {}) {
 
     switch (provider) {
         case SCHEDULER_PROVIDERS.EVENTBRIDGE: {
-            const { EventBridgeSchedulerAdapter } = require('./eventbridge-scheduler-adapter');
+            const { EventBridgeSchedulerAdapter } = require('@friggframework/provider-aws');
             return new EventBridgeSchedulerAdapter({
                 region: options.region,
             });

package/package.json

@@ -1,12 +1,8 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.545.1176a00.0",
+    "version": "2.0.0--canary.545.29ef032.0",
     "dependencies": {
-        "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
-        "@aws-sdk/client-kms": "^3.588.0",
-        "@aws-sdk/client-lambda": "^3.714.0",
-        "@aws-sdk/client-sqs": "^3.588.0",
         "@hapi/boom": "^10.0.1",
         "bcryptjs": "^2.4.3",
         "body-parser": "^1.20.2",
@@ -39,9 +35,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.545.1176a00.0",
-        "@friggframework/prettier-config": "2.0.0--canary.545.1176a00.0",
-        "@friggframework/test": "2.0.0--canary.545.1176a00.0",
+        "@friggframework/eslint-config": "2.0.0--canary.545.29ef032.0",
+        "@friggframework/prettier-config": "2.0.0--canary.545.29ef032.0",
+        "@friggframework/test": "2.0.0--canary.545.29ef032.0",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -82,5 +78,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "1176a004e97f7558574e56aef89ab5fe15ab8e31"
+    "gitHead": "29ef03208c79ed5986a4353e7f1230da52b3b2aa"
 }

package/queues/index.js

@@ -1,12 +1,12 @@
 const { QueuerUtil } = require('./queuer-util');
 const { QueueProvider } = require('./queue-provider');
+const { QueueClientInterface } = require('./queue-client-interface');
 const {
     createQueueProvider,
     determineProvider,
     QUEUE_PROVIDERS,
 } = require('./queue-provider-factory');
 const {
-    SqsQueueProvider,
     NetlifyBackgroundProvider,
     QStashQueueProvider,
 } = require('./providers');
@@ -14,10 +14,10 @@ const {
 module.exports = {
     QueuerUtil,
     QueueProvider,
+    QueueClientInterface,
     createQueueProvider,
     determineProvider,
     QUEUE_PROVIDERS,
-    SqsQueueProvider,
     NetlifyBackgroundProvider,
     QStashQueueProvider,
 };

package/queues/providers/index.js

@@ -1,9 +1,7 @@
-const { SqsQueueProvider } = require('./sqs-queue-provider');
 const { NetlifyBackgroundProvider } = require('./netlify-background-provider');
 const { QStashQueueProvider } = require('./qstash-queue-provider');
 
 module.exports = {
-    SqsQueueProvider,
     NetlifyBackgroundProvider,
     QStashQueueProvider,
 };

package/queues/queue-client-interface.js

@@ -0,0 +1,55 @@
+/**
+ * Queue Client Interface (Port)
+ *
+ * Defines the contract for low-level queue message operations.
+ * Used by Worker class and QueuerUtil for sending/receiving queue messages.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify, QStash, etc.)
+ *
+ * Distinct from QueueProvider which is the higher-level provider for
+ * integration-level queue operations (send/batchSend/parseEvent).
+ * QueueClientInterface is the lower-level "how do I talk to the queue service" port.
+ */
+class QueueClientInterface {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} params
+     * @param {string} params.QueueUrl - Queue endpoint/identifier
+     * @param {string} params.MessageBody - Serialized message body
+     * @param {number} [params.DelaySeconds] - Delay before message becomes visible
+     * @returns {Promise<{MessageId: string}>} Result with message identifier
+     */
+    async sendMessage(params) {
+        throw new Error('Method sendMessage must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object} params
+     * @param {string} params.QueueUrl - Queue endpoint/identifier
+     * @param {Array<{Id: string, MessageBody: string}>} params.Entries - Messages to send
+     * @returns {Promise<Object>} Batch send result
+     */
+    async sendMessageBatch(params) {
+        throw new Error(
+            'Method sendMessageBatch must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Resolve a queue name to a URL/endpoint
+     *
+     * @param {Object} params
+     * @param {string} params.QueueName - Queue name to resolve
+     * @returns {Promise<string>} Resolved queue URL/endpoint
+     */
+    async getQueueUrl(params) {
+        throw new Error('Method getQueueUrl must be implemented by subclass');
+    }
+}
+
+module.exports = { QueueClientInterface };

package/queues/queue-provider-factory.js

@@ -14,11 +14,8 @@
  * - 'netlify-background' → Netlify Background Functions
  * - 'qstash' → Upstash QStash (platform-agnostic)
  */
-const { SqsQueueProvider } = require('./providers/sqs-queue-provider');
-const {
-    NetlifyBackgroundProvider,
-} = require('./providers/netlify-background-provider');
-const { QStashQueueProvider } = require('./providers/qstash-queue-provider');
+// Provider implementations are lazily required inside the switch cases
+// to avoid pulling in AWS SDK on non-AWS platforms.
 
 const QUEUE_PROVIDERS = {
     SQS: 'sqs',
@@ -64,12 +61,18 @@ function createQueueProvider(options = {}) {
     const providerOptions = options.providerOptions || {};
 
     switch (provider) {
-        case QUEUE_PROVIDERS.SQS:
+        case QUEUE_PROVIDERS.SQS: {
+            const { SqsQueueProvider } = require('@friggframework/provider-aws');
             return new SqsQueueProvider(providerOptions);
-        case QUEUE_PROVIDERS.NETLIFY_BACKGROUND:
+        }
+        case QUEUE_PROVIDERS.NETLIFY_BACKGROUND: {
+            const { NetlifyBackgroundProvider } = require('./providers/netlify-background-provider');
             return new NetlifyBackgroundProvider(providerOptions);
-        case QUEUE_PROVIDERS.QSTASH:
+        }
+        case QUEUE_PROVIDERS.QSTASH: {
+            const { QStashQueueProvider } = require('./providers/qstash-queue-provider');
             return new QStashQueueProvider(providerOptions);
+        }
         default:
             throw new Error(
                 `Unknown queue provider: '${provider}'. Supported: ${Object.values(QUEUE_PROVIDERS).join(', ')}`

package/queues/queuer-util.js

@@ -1,34 +1,41 @@
 const { v4: uuid } = require('uuid');
-const {
-    SQSClient,
-    SendMessageCommand,
-    SendMessageBatchCommand,
-} = require('@aws-sdk/client-sqs');
 
-const awsConfigOptions = () => {
-    const config = {};
-    if (process.env.IS_OFFLINE) {
-        config.credentials = {
-            accessKeyId: 'test-aws-key',
-            secretAccessKey: 'test-aws-secret',
-        };
-        config.region = 'us-east-1';
-    }
-    if (process.env.AWS_ENDPOINT) {
-        config.endpoint = process.env.AWS_ENDPOINT;
-    }
-    return config;
-};
+/**
+ * QueuerUtil - Queue message utility.
+ *
+ * BREAKING CHANGE (v3): A queue client must be set via setQueueClient()
+ * before calling send() or batchSend().
+ * For AWS/SQS, pass `new SqsQueueClient()` from @friggframework/provider-aws.
+ * See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.
+ */
+let _queueClient = null;
 
-const sqs = new SQSClient(awsConfigOptions());
+function getQueueClient() {
+    if (!_queueClient) {
+        throw new Error(
+            'QueuerUtil requires a queue client. Call QueuerUtil.setQueueClient() first, e.g.:\n' +
+            '  const { SqsQueueClient } = require("@friggframework/provider-aws");\n' +
+            '  QueuerUtil.setQueueClient(new SqsQueueClient());\n' +
+            'See docs/architecture-decisions/010-decouple-aws-from-core.md for migration guide.'
+        );
+    }
+    return _queueClient;
+}
 
 const QueuerUtil = {
+    /**
+     * Set the queue client. Must be called before send() or batchSend().
+     * @param {QueueClientInterface} client
+     */
+    setQueueClient(client) {
+        _queueClient = client;
+    },
+
     send: async (message, queueUrl) => {
-        const command = new SendMessageCommand({
+        return getQueueClient().sendMessage({
             MessageBody: JSON.stringify(message),
             QueueUrl: queueUrl,
         });
-        return sqs.send(command);
     },
 
     batchSend: async (entries = [], queueUrl) => {
@@ -42,23 +49,20 @@ const QueuerUtil = {
             });
             // Sends 10, then purges the buffer
             if (buffer.length === batchSize) {
-                const command = new SendMessageBatchCommand({
-                    Entries: buffer,
+                await getQueueClient().sendMessageBatch({
+                    Entries: [...buffer],
                     QueueUrl: queueUrl,
                 });
-                await sqs.send(command);
-                // Purge the buffer
-                buffer.splice(0, buffer.length);
+                buffer.length = 0;
             }
         }
 
         // If any remaining entries under 10 are left in the buffer, send and return
         if (buffer.length > 0) {
-            const command = new SendMessageBatchCommand({
+            return getQueueClient().sendMessageBatch({
                 Entries: buffer,
                 QueueUrl: queueUrl,
             });
-            return sqs.send(command);
         }
 
         // If we're exact... just return an empty object for now