@friggframework/devtools 2.0.0--canary.629.1a7ad06.0 → 2.0.0--canary.640.b31eb4a.0

package/infrastructure/__tests__/aurora-scale-to-zero-connectivity.test.js

@@ -0,0 +1,255 @@
+/**
+ * ADR-033: Aurora Serverless v2 scale-to-zero + NAT-free public connectivity
+ *
+ * These tests assert on the GENERATED CloudFormation template (via the full
+ * composer) plus the AuroraBuilder validator. They are deterministic and require
+ * neither a live AWS account nor Prisma client generation:
+ *   - Validator cases call AuroraBuilder.validate() directly (pure, no I/O).
+ *   - Template cases use vpc.management='create-new' + database.postgres
+ *     management='managed', which resolve to STACK ownership without depending on
+ *     any discovered AWS resource, so cloud discovery returning empty is fine.
+ *
+ * Both new capabilities are opt-in and default-off; the final describe block
+ * guards the no-regression promise: a default (vpc, no minCapacity) definition
+ * composes the same template as before.
+ */
+
+const { composeServerlessDefinition } = require('../infrastructure-composer');
+const { AuroraBuilder } = require('../domains/database/aurora-builder');
+
+// Shared: an app definition that creates a fresh VPC + a Frigg-owned Aurora
+// cluster in-stack, with overridable postgres config.
+function makeApp(postgresOverrides = {}) {
+    return {
+        name: 'adr033-app',
+        provider: 'aws',
+        region: 'us-east-1',
+        integrations: [],
+        vpc: { enable: true, management: 'create-new' },
+        database: {
+            postgres: {
+                enable: true,
+                management: 'managed',
+                ...postgresOverrides,
+            },
+        },
+    };
+}
+
+function findResources(template, predicate) {
+    return Object.entries(template.resources.Resources).filter(([, r]) => predicate(r));
+}
+
+describe('ADR-033: Aurora scale-to-zero + connectivity', () => {
+    beforeAll(() => {
+        process.env.AWS_REGION = 'us-east-1';
+        // Intentionally NOT setting FRIGG_SKIP_AWS_DISCOVERY — the builders must
+        // execute. create-new/managed resolve to STACK without needing discovery.
+    });
+
+    afterAll(() => {
+        delete process.env.AWS_REGION;
+    });
+
+    // ---------------------------------------------------------------------
+    // Validator
+    // ---------------------------------------------------------------------
+    describe('validator (AuroraBuilder.validate)', () => {
+        const build = new AuroraBuilder();
+        // ValidationResult exposes hasErrors(); "valid" means no errors.
+        const validateResult = (postgres) =>
+            build.validate({ database: { postgres: { enable: true, ...postgres } } });
+        const isValid = (postgres) => !validateResult(postgres).hasErrors();
+
+        test('accepts minCapacity: 0 (scale-to-zero)', () => {
+            expect(isValid({ minCapacity: 0 })).toBe(true);
+        });
+
+        test('rejects minCapacity: 0.3 (inside the forbidden (0, 0.5) band)', () => {
+            const r = validateResult({ minCapacity: 0.3 });
+            expect(r.hasErrors()).toBe(true);
+            expect(r.errors.join(' ')).toMatch(/minCapacity must be 0 \(scale-to-zero\) or between 0\.5 and 128/);
+        });
+
+        test('accepts minCapacity: 0.5 and minCapacity: 64', () => {
+            expect(isValid({ minCapacity: 0.5 })).toBe(true);
+            expect(isValid({ minCapacity: 64 })).toBe(true);
+        });
+
+        test('rejects secondsUntilAutoPause: 100 (below 300)', () => {
+            const r = validateResult({ minCapacity: 0, secondsUntilAutoPause: 100 });
+            expect(r.hasErrors()).toBe(true);
+            expect(r.errors.join(' ')).toMatch(/secondsUntilAutoPause must be an integer between 300 and 86400/);
+        });
+
+        test('accepts secondsUntilAutoPause: 3600', () => {
+            expect(isValid({ minCapacity: 0, secondsUntilAutoPause: 3600 })).toBe(true);
+        });
+
+        test("accepts connectivity: 'public'", () => {
+            expect(isValid({ connectivity: 'public' })).toBe(true);
+        });
+
+        test("rejects connectivity: 'nope'", () => {
+            const r = validateResult({ connectivity: 'nope' });
+            expect(r.hasErrors()).toBe(true);
+            expect(r.errors.join(' ')).toMatch(/Invalid database\.postgres\.connectivity/);
+        });
+
+        test('rejects non-array / non-CIDR allowedCidrs, accepts valid CIDRs', () => {
+            expect(isValid({ allowedCidrs: 'nope' })).toBe(false);
+            expect(isValid({ allowedCidrs: ['not-a-cidr'] })).toBe(false);
+            expect(isValid({ allowedCidrs: ['10.0.0.0/8', '203.0.113.5/32'] })).toBe(true);
+        });
+
+        test('warns (does not fail) when minCapacity:0 with an older pinned engine version', () => {
+            const r = validateResult({ minCapacity: 0, engineVersion: '15.4' });
+            expect(r.hasErrors()).toBe(false); // warning, not error
+            expect(r.warnings.join(' ')).toMatch(/may not support .*scale-to-zero/);
+        });
+
+        test('does not warn about engine when minCapacity:0 on a capable version', () => {
+            const r = validateResult({ minCapacity: 0, engineVersion: '15.13' });
+            expect(r.warnings.join(' ')).not.toMatch(/may not support .*scale-to-zero/);
+        });
+    });
+
+    // ---------------------------------------------------------------------
+    // Scale-to-zero (template shape)
+    // ---------------------------------------------------------------------
+    describe('scale-to-zero (minCapacity: 0)', () => {
+        test('MinCapacity is exactly 0 and SecondsUntilAutoPause defaults to 300', async () => {
+            const t = await composeServerlessDefinition(makeApp({ minCapacity: 0 }));
+            const scaling = t.resources.Resources.FriggAuroraCluster.Properties.ServerlessV2ScalingConfiguration;
+
+            // Mutation guard: with the old `|| 0.5` bug this would be 0.5, not 0.
+            expect(scaling.MinCapacity).toBe(0);
+            expect(scaling.MinCapacity).not.toBe(0.5);
+            expect(scaling.SecondsUntilAutoPause).toBe(300);
+        });
+
+        test('SecondsUntilAutoPause honors a custom value', async () => {
+            const t = await composeServerlessDefinition(makeApp({ minCapacity: 0, secondsUntilAutoPause: 1800 }));
+            const scaling = t.resources.Resources.FriggAuroraCluster.Properties.ServerlessV2ScalingConfiguration;
+            expect(scaling.MinCapacity).toBe(0);
+            expect(scaling.SecondsUntilAutoPause).toBe(1800);
+        });
+
+        test('MaxCapacity defaults to 4 and is preserved with scale-to-zero', async () => {
+            const t = await composeServerlessDefinition(makeApp({ minCapacity: 0 }));
+            const scaling = t.resources.Resources.FriggAuroraCluster.Properties.ServerlessV2ScalingConfiguration;
+            expect(scaling.MaxCapacity).toBe(4);
+        });
+    });
+
+    // ---------------------------------------------------------------------
+    // Public connectivity (template shape)
+    // ---------------------------------------------------------------------
+    describe("connectivity: 'public'", () => {
+        test('Aurora ingress uses CidrIp — one rule per allowedCidr — not SourceSecurityGroupId', async () => {
+            const t = await composeServerlessDefinition(
+                makeApp({ connectivity: 'public', allowedCidrs: ['10.1.0.0/16', '203.0.113.7/32'] })
+            );
+            const ingress = findResources(
+                t,
+                (r) => r.Type === 'AWS::EC2::SecurityGroupIngress' && r.Properties.FromPort === 5432
+            );
+            expect(ingress).toHaveLength(2);
+            const cidrs = ingress.map(([, r]) => r.Properties.CidrIp).sort();
+            expect(cidrs).toEqual(['10.1.0.0/16', '203.0.113.7/32']);
+            ingress.forEach(([, r]) => {
+                expect(r.Properties.CidrIp).toBeDefined();
+                expect(r.Properties.SourceSecurityGroupId).toBeUndefined();
+            });
+        });
+
+        test('allowedCidrs defaults to 0.0.0.0/0 when omitted', async () => {
+            const t = await composeServerlessDefinition(makeApp({ connectivity: 'public' }));
+            const ingress = findResources(
+                t,
+                (r) => r.Type === 'AWS::EC2::SecurityGroupIngress' && r.Properties.FromPort === 5432
+            );
+            expect(ingress).toHaveLength(1);
+            expect(ingress[0][1].Properties.CidrIp).toBe('0.0.0.0/0');
+        });
+
+        test('Aurora instance is PubliclyAccessible and cluster sits in public subnets', async () => {
+            const t = await composeServerlessDefinition(makeApp({ connectivity: 'public' }));
+            expect(t.resources.Resources.FriggAuroraInstance.Properties.PubliclyAccessible).toBe(true);
+            expect(t.resources.Resources.FriggDBSubnetGroup.Properties.SubnetIds).toEqual([
+                { Ref: 'FriggPublicSubnet' },
+                { Ref: 'FriggPublicSubnet2' },
+            ]);
+        });
+
+        test('NO NAT Gateway resource is emitted', async () => {
+            const t = await composeServerlessDefinition(makeApp({ connectivity: 'public' }));
+            const nats = findResources(t, (r) => r.Type === 'AWS::EC2::NatGateway');
+            expect(nats).toHaveLength(0);
+        });
+
+        test('Lambda is NOT attached to the VPC (provider.vpc unset)', async () => {
+            const t = await composeServerlessDefinition(makeApp({ connectivity: 'public' }));
+            expect(t.provider.vpc).toBeUndefined();
+        });
+
+        test('DATABASE_URL enforces TLS (sslmode=require)', async () => {
+            const t = await composeServerlessDefinition(makeApp({ connectivity: 'public' }));
+            const url = t.provider.environment.DATABASE_URL;
+            expect(url['Fn::Sub'][0]).toContain('sslmode=require');
+        });
+
+        test('combines with scale-to-zero: $0-idle NAT-free Aurora', async () => {
+            const t = await composeServerlessDefinition(makeApp({ connectivity: 'public', minCapacity: 0 }));
+            const scaling = t.resources.Resources.FriggAuroraCluster.Properties.ServerlessV2ScalingConfiguration;
+            expect(scaling.MinCapacity).toBe(0);
+            expect(scaling.SecondsUntilAutoPause).toBe(300);
+            expect(findResources(t, (r) => r.Type === 'AWS::EC2::NatGateway')).toHaveLength(0);
+            expect(t.provider.vpc).toBeUndefined();
+        });
+    });
+
+    // ---------------------------------------------------------------------
+    // No-regression: default (vpc) connectivity, no new fields
+    // ---------------------------------------------------------------------
+    describe("default connectivity: 'vpc' (no regression)", () => {
+        test('MinCapacity defaults to 0.5 with no SecondsUntilAutoPause', async () => {
+            const t = await composeServerlessDefinition(makeApp());
+            const scaling = t.resources.Resources.FriggAuroraCluster.Properties.ServerlessV2ScalingConfiguration;
+            expect(scaling.MinCapacity).toBe(0.5);
+            expect(scaling.MaxCapacity).toBe(4);
+            expect(scaling.SecondsUntilAutoPause).toBeUndefined();
+        });
+
+        test('Aurora ingress uses SourceSecurityGroupId (Lambda SG), not CidrIp', async () => {
+            const t = await composeServerlessDefinition(makeApp());
+            const ingress = findResources(
+                t,
+                (r) => r.Type === 'AWS::EC2::SecurityGroupIngress' && r.Properties.FromPort === 5432
+            );
+            expect(ingress).toHaveLength(1);
+            expect(ingress[0][1].Properties.SourceSecurityGroupId).toEqual({ Ref: 'FriggLambdaSecurityGroup' });
+            expect(ingress[0][1].Properties.CidrIp).toBeUndefined();
+            // Logical ID unchanged for the vpc path
+            expect(ingress[0][0]).toBe('FriggAuroraIngressRule');
+        });
+
+        test('Aurora instance is not publicly accessible by default', async () => {
+            const t = await composeServerlessDefinition(makeApp());
+            expect(t.resources.Resources.FriggAuroraInstance.Properties.PubliclyAccessible).toBe(false);
+        });
+
+        test('Lambda IS attached to the VPC (provider.vpc set)', async () => {
+            const t = await composeServerlessDefinition(makeApp());
+            expect(t.provider.vpc).toBeDefined();
+            expect(t.provider.vpc.subnetIds).toBeDefined();
+            expect(t.provider.vpc.securityGroupIds).toBeDefined();
+        });
+
+        test('DATABASE_URL does not add sslmode in vpc mode', async () => {
+            const t = await composeServerlessDefinition(makeApp());
+            const url = t.provider.environment.DATABASE_URL;
+            expect(url['Fn::Sub'][0]).not.toContain('sslmode=require');
+        });
+    });
+});

package/infrastructure/domains/database/aurora-builder.js

@@ -94,21 +94,123 @@ class AuroraBuilder extends InfrastructureBuilder {
         }
 
         // Validate capacity settings
-        if (dbConfig.minCapacity !== undefined && (dbConfig.minCapacity < 0.5 || dbConfig.minCapacity > 128)) {
-            result.addError('database.postgres.minCapacity must be between 0.5 and 128');
+        // minCapacity accepts 0 (Aurora Serverless v2 scale-to-zero, GA Nov 2024)
+        // OR a value in [0.5, 128]. Values in (0, 0.5) are not a valid Aurora
+        // capacity — reject them explicitly. See ADR-033.
+        if (
+            dbConfig.minCapacity !== undefined &&
+            dbConfig.minCapacity !== 0 &&
+            (dbConfig.minCapacity < 0.5 || dbConfig.minCapacity > 128)
+        ) {
+            result.addError('database.postgres.minCapacity must be 0 (scale-to-zero) or between 0.5 and 128');
         }
         if (dbConfig.maxCapacity !== undefined && (dbConfig.maxCapacity < 0.5 || dbConfig.maxCapacity > 128)) {
             result.addError('database.postgres.maxCapacity must be between 0.5 and 128');
         }
 
+        // Validate scale-to-zero auto-pause window (seconds). AWS-valid range is
+        // 300–86400 (5 minutes to 24 hours) and it must be an integer.
+        if (dbConfig.secondsUntilAutoPause !== undefined) {
+            const s = dbConfig.secondsUntilAutoPause;
+            if (!Number.isInteger(s) || s < 300 || s > 86400) {
+                result.addError('database.postgres.secondsUntilAutoPause must be an integer between 300 and 86400');
+            }
+        }
+
+        // Validate connectivity mode. 'vpc' (default) keeps today's behavior;
+        // 'public' places Aurora in public subnets and leaves the Lambda out of
+        // the VPC (NAT-free). See ADR-033.
+        if (dbConfig.connectivity !== undefined) {
+            const validConnectivity = ['vpc', 'public'];
+            if (!validConnectivity.includes(dbConfig.connectivity)) {
+                result.addError(
+                    `Invalid database.postgres.connectivity: "${dbConfig.connectivity}". Must be one of: ${validConnectivity.join(', ')}`
+                );
+            }
+        }
+
+        // Validate allowedCidrs is an array of CIDR-looking strings when present.
+        if (dbConfig.allowedCidrs !== undefined) {
+            const cidrPattern = /^([0-9]{1,3}\.){3}[0-9]{1,3}\/[0-9]{1,2}$/;
+            if (!Array.isArray(dbConfig.allowedCidrs)) {
+                result.addError('database.postgres.allowedCidrs must be an array of CIDR strings');
+            } else {
+                const bad = dbConfig.allowedCidrs.filter(
+                    (c) => typeof c !== 'string' || !cidrPattern.test(c)
+                );
+                if (bad.length > 0) {
+                    result.addError(
+                        `database.postgres.allowedCidrs contains invalid CIDR value(s): ${bad.join(', ')}`
+                    );
+                }
+            }
+        }
+
+        // Scale-to-zero requires a supported engine version. Warn (do not
+        // hard-fail) if the user pins an older version with minCapacity: 0.
+        // Frigg's default engineVersion (15.13) qualifies. Minimum
+        // scale-to-zero-capable versions: Aurora PG 13.15 / 14.12 / 15.7 / 16.3.
+        if (dbConfig.minCapacity === 0 && dbConfig.engineVersion) {
+            if (!this.engineSupportsScaleToZero(dbConfig.engineVersion)) {
+                result.addWarning(
+                    `database.postgres.engineVersion="${dbConfig.engineVersion}" may not support Aurora Serverless v2 scale-to-zero (minCapacity: 0). ` +
+                        'Scale-to-zero requires Aurora PostgreSQL 13.15+/14.12+/15.7+/16.3+.'
+                );
+            }
+        }
+
         // Warn about public accessibility in production
         if (dbConfig.publiclyAccessible === true) {
             result.addWarning('database.postgres.publiclyAccessible=true is not recommended for production');
         }
 
+        // ADR-033 security posture: public connectivity exposes the DB endpoint
+        // to the internet. Make the trade-off loud.
+        if (dbConfig.connectivity === 'public') {
+            result.addWarning(
+                'database.postgres.connectivity="public" exposes the Aurora endpoint to the internet. ' +
+                    'TLS is enforced (sslmode=require) and access is restricted to allowedCidrs, but prefer "vpc" for production.'
+            );
+            const cidrs = Array.isArray(dbConfig.allowedCidrs) ? dbConfig.allowedCidrs : ['0.0.0.0/0'];
+            if (cidrs.includes('0.0.0.0/0')) {
+                result.addWarning(
+                    'database.postgres.allowedCidrs allows 0.0.0.0/0 (the whole internet). ' +
+                        'Narrow this to known egress ranges wherever the deployment can.'
+                );
+            }
+        }
+
         return result;
     }
 
+    /**
+     * Determine whether an Aurora PostgreSQL engine version supports
+     * Serverless v2 scale-to-zero (minCapacity: 0). Minimum capable versions:
+     * 13.15+, 14.12+, 15.7+, 16.3+. Unknown/unparseable versions return true
+     * (assume-capable) so we never hard-block on a version string we can't read;
+     * this only gates a warning, never a hard failure.
+     * @param {string} engineVersion e.g. '15.13'
+     * @returns {boolean}
+     */
+    engineSupportsScaleToZero(engineVersion) {
+        const minByMajor = { 13: 15, 14: 12, 15: 7, 16: 3 };
+        const match = /^(\d+)\.(\d+)/.exec(String(engineVersion));
+        if (!match) {
+            return true; // can't parse — don't warn spuriously
+        }
+        const major = Number(match[1]);
+        const minor = Number(match[2]);
+        // Majors newer than the table are assumed capable.
+        if (major > 16) {
+            return true;
+        }
+        // Majors older than 13 never support scale-to-zero.
+        if (!(major in minByMajor)) {
+            return false;
+        }
+        return minor >= minByMajor[major];
+    }
+
     /**
      * Build Aurora infrastructure using ownership-based architecture
      */
@@ -327,16 +429,27 @@ class AuroraBuilder extends InfrastructureBuilder {
             }
         }
 
-        // Preserve other database config
-        if (appDefinition.database?.postgres?.minCapacity) {
+        // Preserve other database config.
+        // NOTE: use `!== undefined` (not truthiness) so a requested minCapacity
+        // of 0 (scale-to-zero) flows through instead of being dropped.
+        if (appDefinition.database?.postgres?.minCapacity !== undefined) {
             translated.database.postgres.config.minCapacity = appDefinition.database.postgres.minCapacity;
         }
-        if (appDefinition.database?.postgres?.maxCapacity) {
+        if (appDefinition.database?.postgres?.maxCapacity !== undefined) {
             translated.database.postgres.config.maxCapacity = appDefinition.database.postgres.maxCapacity;
         }
+        if (appDefinition.database?.postgres?.secondsUntilAutoPause !== undefined) {
+            translated.database.postgres.config.secondsUntilAutoPause = appDefinition.database.postgres.secondsUntilAutoPause;
+        }
         if (appDefinition.database?.postgres?.publiclyAccessible !== undefined) {
             translated.database.postgres.config.publiclyAccessible = appDefinition.database.postgres.publiclyAccessible;
         }
+        if (appDefinition.database?.postgres?.connectivity !== undefined) {
+            translated.database.postgres.config.connectivity = appDefinition.database.postgres.connectivity;
+        }
+        if (appDefinition.database?.postgres?.allowedCidrs !== undefined) {
+            translated.database.postgres.config.allowedCidrs = appDefinition.database.postgres.allowedCidrs;
+        }
 
         return translated;
     }
@@ -373,7 +486,10 @@ class AuroraBuilder extends InfrastructureBuilder {
         console.log('  Creating new Aurora Serverless v2 cluster...');
 
         const dbConfig = appDefinition.database.postgres;
-        const publiclyAccessible = dbConfig.publiclyAccessible === true;
+        // ADR-033: connectivity 'public' implies a publicly-accessible cluster in
+        // public subnets. It combines with the legacy publiclyAccessible flag.
+        const publicConnectivity = dbConfig.connectivity === 'public';
+        const publiclyAccessible = publicConnectivity || dbConfig.publiclyAccessible === true;
 
         // Get subnet IDs for DB Subnet Group
         const subnetIds = publiclyAccessible
@@ -452,9 +568,16 @@ class AuroraBuilder extends InfrastructureBuilder {
                 // min when idle) and gives the DB enough headroom to
                 // absorb bursty sync traffic. Apps can still override both
                 // via app definition dbConfig.
+                // ADR-033: use nullish coalescing — `|| 0.5` silently turned a
+                // requested MinCapacity of 0 (scale-to-zero) back into 0.5.
+                // When MinCapacity is 0, emit SecondsUntilAutoPause so the cluster
+                // pauses to 0 ACU after the idle window (default 300s).
                 ServerlessV2ScalingConfiguration: {
-                    MinCapacity: dbConfig.minCapacity || 0.5,
-                    MaxCapacity: dbConfig.maxCapacity || 4,
+                    MinCapacity: dbConfig.minCapacity ?? 0.5,
+                    MaxCapacity: dbConfig.maxCapacity ?? 4,
+                    ...(dbConfig.minCapacity === 0
+                        ? { SecondsUntilAutoPause: dbConfig.secondsUntilAutoPause ?? 300 }
+                        : {}),
                 },
                 EnableHttpEndpoint: false,
                 BackupRetentionPeriod: 7,
@@ -482,12 +605,15 @@ class AuroraBuilder extends InfrastructureBuilder {
             },
         };
 
-        // Environment variables
+        // Environment variables.
+        // ADR-033: public connectivity requires TLS (sslmode=require) since the
+        // endpoint is reachable over the internet.
         result.environment.DATABASE_URL = this.buildDatabaseUrl(
             { 'Fn::GetAtt': ['FriggAuroraCluster', 'Endpoint.Address'] },
             { 'Fn::GetAtt': ['FriggAuroraCluster', 'Endpoint.Port'] },
             dbConfig.database || 'frigg',
-            { Ref: 'FriggDBSecret' }
+            { Ref: 'FriggDBSecret' },
+            { requireTls: publicConnectivity }
         );
 
         // IAM permissions for Secrets Manager
@@ -497,19 +623,46 @@ class AuroraBuilder extends InfrastructureBuilder {
             Resource: { Ref: 'FriggDBSecret' },
         });
 
-        // Add self-referencing security group ingress rule to allow Lambda to connect to Aurora
-        // Since both Lambda and Aurora share the same security group, we need to allow the SG to accept traffic from itself
-        result.resources.FriggAuroraIngressRule = {
-            Type: 'AWS::EC2::SecurityGroupIngress',
-            Properties: {
-                GroupId: { Ref: 'FriggLambdaSecurityGroup' },
-                IpProtocol: 'tcp',
-                FromPort: 5432,
-                ToPort: 5432,
-                SourceSecurityGroupId: { Ref: 'FriggLambdaSecurityGroup' },
-                Description: 'Allow Lambda functions to connect to Aurora PostgreSQL (self-referencing rule)',
-            },
-        };
+        if (publicConnectivity) {
+            // ADR-033 NAT-free public connectivity: the Lambda is NOT attached to
+            // the VPC (see vpc-builder), so FriggLambdaSecurityGroup is not on the
+            // Lambda side and a SourceSecurityGroupId rule would authorize nothing.
+            // Instead open 5432 to the configured CIDR allowlist (default
+            // 0.0.0.0/0 for demos — narrow it in production). One ingress rule per
+            // CIDR. GroupId stays FriggLambdaSecurityGroup because that is the SG
+            // attached to the Aurora cluster (see VpcSecurityGroupIds above).
+            const allowedCidrs =
+                Array.isArray(dbConfig.allowedCidrs) && dbConfig.allowedCidrs.length > 0
+                    ? dbConfig.allowedCidrs
+                    : ['0.0.0.0/0'];
+            allowedCidrs.forEach((cidr, index) => {
+                result.resources[`FriggAuroraIngressRule${index}`] = {
+                    Type: 'AWS::EC2::SecurityGroupIngress',
+                    Properties: {
+                        GroupId: { Ref: 'FriggLambdaSecurityGroup' },
+                        IpProtocol: 'tcp',
+                        FromPort: 5432,
+                        ToPort: 5432,
+                        CidrIp: cidr,
+                        Description: `Allow PostgreSQL access from ${cidr} (public connectivity)`,
+                    },
+                };
+            });
+        } else {
+            // Add self-referencing security group ingress rule to allow Lambda to connect to Aurora
+            // Since both Lambda and Aurora share the same security group, we need to allow the SG to accept traffic from itself
+            result.resources.FriggAuroraIngressRule = {
+                Type: 'AWS::EC2::SecurityGroupIngress',
+                Properties: {
+                    GroupId: { Ref: 'FriggLambdaSecurityGroup' },
+                    IpProtocol: 'tcp',
+                    FromPort: 5432,
+                    ToPort: 5432,
+                    SourceSecurityGroupId: { Ref: 'FriggLambdaSecurityGroup' },
+                    Description: 'Allow Lambda functions to connect to Aurora PostgreSQL (self-referencing rule)',
+                },
+            };
+        }
 
         console.log('  ✅ Aurora Serverless v2 cluster resources created');
     }
@@ -554,6 +707,9 @@ class AuroraBuilder extends InfrastructureBuilder {
         console.log(`  ✅ Using discovered Aurora cluster: ${discoveredResources.auroraClusterEndpoint}`);
 
         const dbConfig = appDefinition.database.postgres;
+        // ADR-033: public connectivity requires TLS on the connection string and a
+        // CIDR-based ingress rule (the Lambda is not VPC-attached).
+        const publicConnectivity = dbConfig.connectivity === 'public';
 
         // Use discovered cluster details
         result.environment.DATABASE_HOST = discoveredResources.auroraClusterEndpoint;
@@ -729,7 +885,8 @@ exports.handler = async (event, context) => {
                 discoveredResources.auroraClusterEndpoint,
                 discoveredResources.auroraPort || 5432,
                 dbConfig.database || 'frigg',
-                { Ref: 'FriggDBSecret' }
+                { Ref: 'FriggDBSecret' },
+                { requireTls: publicConnectivity }
             );
 
             // Grant Lambda functions permission to read the secret
@@ -747,7 +904,8 @@ exports.handler = async (event, context) => {
                 discoveredResources.auroraClusterEndpoint,
                 discoveredResources.auroraPort || 5432,
                 dbConfig.database || 'frigg',
-                discoveredResources.databaseSecretArn
+                discoveredResources.databaseSecretArn,
+                { requireTls: publicConnectivity }
             );
 
             result.iamStatements.push({
@@ -768,7 +926,10 @@ exports.handler = async (event, context) => {
             // Consumers that build DATABASE_URL from components at runtime MUST
             // append `?${DATABASE_URL_PARAMS}` to get the same hang-prevention
             // timeouts as the managed path.
-            result.environment.DATABASE_URL_PARAMS = LAMBDA_DATABASE_URL_QUERY_PARAMS;
+            // ADR-033: public connectivity requires TLS — include sslmode=require.
+            result.environment.DATABASE_URL_PARAMS = publicConnectivity
+                ? `${LAMBDA_DATABASE_URL_QUERY_PARAMS}&sslmode=require`
+                : LAMBDA_DATABASE_URL_QUERY_PARAMS;
 
             // Note: DATABASE_URL is NOT set here to avoid Serverless variable resolution errors
             // The application (Frigg Core) should construct it at runtime from:
@@ -782,17 +943,39 @@ exports.handler = async (event, context) => {
 
         // Add security group ingress rule to allow Lambda to connect to Aurora
         if (discoveredResources.auroraSecurityGroupId) {
-            result.resources.FriggAuroraIngressRule = {
-                Type: 'AWS::EC2::SecurityGroupIngress',
-                Properties: {
-                    GroupId: discoveredResources.auroraSecurityGroupId,
-                    IpProtocol: 'tcp',
-                    FromPort: discoveredResources.auroraPort || 5432,
-                    ToPort: discoveredResources.auroraPort || 5432,
-                    SourceSecurityGroupId: { Ref: 'FriggLambdaSecurityGroup' },
-                    Description: 'Allow Lambda functions to connect to Aurora PostgreSQL',
-                },
-            };
+            if (publicConnectivity) {
+                // ADR-033 NAT-free public connectivity: the Lambda is not in the
+                // VPC, so authorize the CIDR allowlist instead of the Lambda SG.
+                const allowedCidrs =
+                    Array.isArray(dbConfig.allowedCidrs) && dbConfig.allowedCidrs.length > 0
+                        ? dbConfig.allowedCidrs
+                        : ['0.0.0.0/0'];
+                allowedCidrs.forEach((cidr, index) => {
+                    result.resources[`FriggAuroraIngressRule${index}`] = {
+                        Type: 'AWS::EC2::SecurityGroupIngress',
+                        Properties: {
+                            GroupId: discoveredResources.auroraSecurityGroupId,
+                            IpProtocol: 'tcp',
+                            FromPort: discoveredResources.auroraPort || 5432,
+                            ToPort: discoveredResources.auroraPort || 5432,
+                            CidrIp: cidr,
+                            Description: `Allow PostgreSQL access from ${cidr} (public connectivity)`,
+                        },
+                    };
+                });
+            } else {
+                result.resources.FriggAuroraIngressRule = {
+                    Type: 'AWS::EC2::SecurityGroupIngress',
+                    Properties: {
+                        GroupId: discoveredResources.auroraSecurityGroupId,
+                        IpProtocol: 'tcp',
+                        FromPort: discoveredResources.auroraPort || 5432,
+                        ToPort: discoveredResources.auroraPort || 5432,
+                        SourceSecurityGroupId: { Ref: 'FriggLambdaSecurityGroup' },
+                        Description: 'Allow Lambda functions to connect to Aurora PostgreSQL',
+                    },
+                };
+            }
             console.log(`  ✅ Added security group ingress rule for Lambda → Aurora connectivity`);
         }
 
@@ -805,8 +988,11 @@ exports.handler = async (event, context) => {
      * @param {string|number|object} port - Database port (string/number or CloudFormation intrinsic function)
      * @param {string} database - Database name
      * @param {string|object} secretRef - Secret ARN (string) or CloudFormation Ref object
+     * @param {object} [options]
+     * @param {boolean} [options.requireTls] - Append sslmode=require (ADR-033 public connectivity)
      */
-    buildDatabaseUrl(host, port, database, secretRef) {
+    buildDatabaseUrl(host, port, database, secretRef, options = {}) {
+        const { requireTls = false } = options;
         // Handle secretRef as either a string ARN or CloudFormation Ref object
         const resolveSecretRef = (secretRefValue) => {
             if (typeof secretRefValue === 'object' && secretRefValue.Ref) {
@@ -838,9 +1024,16 @@ exports.handler = async (event, context) => {
 
         // Query params are defined at module scope (LAMBDA_DATABASE_URL_QUERY_PARAMS)
         // so runtime-URL-construction paths can emit the same timeouts as an env var.
+        // ADR-033: for public connectivity, TLS is mandatory — append sslmode=require
+        // unless it's already present in the base params.
+        const queryParams =
+            requireTls && !/(^|&)sslmode=/.test(LAMBDA_DATABASE_URL_QUERY_PARAMS)
+                ? `${LAMBDA_DATABASE_URL_QUERY_PARAMS}&sslmode=require`
+                : LAMBDA_DATABASE_URL_QUERY_PARAMS;
+
         return {
             'Fn::Sub': [
-                `postgresql://\${Username}:\${Password}@\${Host}:\${Port}/\${Database}?${LAMBDA_DATABASE_URL_QUERY_PARAMS}`,
+                `postgresql://\${Username}:\${Password}@\${Host}:\${Port}/\${Database}?${queryParams}`,
                 {
                     Username: resolveSecretRef(secretRef),
                     Password: resolveSecretPassword(secretRef),

package/infrastructure/domains/networking/vpc-builder.js

@@ -24,6 +24,31 @@ const { createEmptyDiscoveryResult } = require('../shared/types/discovery-result
 const { ResourceOwnership } = require('../shared/types/resource-ownership');
 const { isSsmOffloadActive } = require('../parameters/offload-utils');
 
+/**
+ * ADR-033: NAT-free public database connectivity.
+ *
+ * When the app opts into `database.postgres.connectivity: 'public'`, Aurora is
+ * placed in public subnets with a public endpoint and the app's Lambdas are
+ * intentionally left OUTSIDE the VPC so they keep default internet egress and
+ * need no NAT Gateway. This function is the single seam that DECOUPLES the
+ * Lambda's VPC attachment + NAT from Aurora's networking:
+ *
+ *   - The VpcBuilder still builds the VPC / public subnets / DB subnet group
+ *     that Aurora requires (Aurora must live in a VPC — an AWS constraint).
+ *   - But it does NOT emit a NAT Gateway, and it clears `result.vpcConfig` so the
+ *     composer never sets `provider.vpc` (see infrastructure-composer.js:126) —
+ *     leaving the Lambda un-attached with normal egress.
+ *
+ * @param {Object} appDefinition
+ * @returns {boolean}
+ */
+function isPublicDatabaseConnectivity(appDefinition) {
+    return (
+        appDefinition?.database?.postgres?.enable === true &&
+        appDefinition?.database?.postgres?.connectivity === 'public'
+    );
+}
+
 class VpcBuilder extends InfrastructureBuilder {
     constructor() {
         super();
@@ -565,11 +590,35 @@ class VpcBuilder extends InfrastructureBuilder {
         // Build Subnets based on ownership decision
         this.buildSubnetsFromDecision(decisions.subnets, appDefinition, discoveredResources, result);
 
-        // Build NAT Gateway based on ownership decision
-        this.buildNatGatewayFromDecision(decisions.natGateway, appDefinition, discoveredResources, result);
+        // ADR-033: NAT-free public database connectivity. When set, Aurora sits in
+        // public subnets with a public endpoint and the Lambda is NOT attached to
+        // the VPC — so it keeps default internet egress and needs no NAT Gateway.
+        // We still built the VPC + public subnets above (Aurora requires them), but
+        // we skip the NAT Gateway here and clear vpcConfig below so the composer
+        // leaves provider.vpc unset. This is the seam that decouples the Lambda's
+        // VPC attachment + NAT from Aurora's networking.
+        const publicDbConnectivity = isPublicDatabaseConnectivity(appDefinition);
+
+        if (publicDbConnectivity) {
+            console.log(
+                '  ⊝ NAT Gateway skipped (database.postgres.connectivity=public — Lambda is not VPC-attached, so no NAT is needed)'
+            );
+        } else {
+            // Build NAT Gateway based on ownership decision
+            this.buildNatGatewayFromDecision(decisions.natGateway, appDefinition, discoveredResources, result);
+        }
 
-        // Build VPC Endpoints based on ownership decisions
-        this.buildVpcEndpointsFromDecisions(decisions.vpcEndpoints, decisions.securityGroup, appDefinition, discoveredResources, result);
+        // Build VPC Endpoints based on ownership decisions.
+        // ADR-033: in public connectivity the Lambda is not in the VPC, so VPC
+        // endpoints (which give in-VPC functions private AWS access) would be
+        // wasted spend — skip them along with the NAT Gateway.
+        if (publicDbConnectivity) {
+            console.log(
+                '  ⊝ VPC Endpoints skipped (database.postgres.connectivity=public — Lambda is not VPC-attached)'
+            );
+        } else {
+            this.buildVpcEndpointsFromDecisions(decisions.vpcEndpoints, decisions.securityGroup, appDefinition, discoveredResources, result);
+        }
 
         // Set VPC_ENABLED environment variable
         result.environment.VPC_ENABLED = 'true';
@@ -579,6 +628,18 @@ class VpcBuilder extends InfrastructureBuilder {
         console.log(`  - Subnets: ${result.vpcConfig.subnetIds.length}`);
         console.log(`  - Security Groups: ${result.vpcConfig.securityGroupIds.length}`);
 
+        if (publicDbConnectivity) {
+            // Do NOT attach the Lambda to the VPC: leaving vpcConfig null means the
+            // composer never sets provider.vpc, so the function keeps normal
+            // internet egress. The Aurora subnets/DB subnet group built above are
+            // still emitted (AuroraBuilder consumes discoveredResources.publicSubnetId*),
+            // and the Lambda reaches Aurora over its public endpoint + TLS.
+            console.log(
+                '  ⊝ Lambda VPC attachment skipped (database.postgres.connectivity=public — provider.vpc will be unset)'
+            );
+            result.vpcConfig = null;
+        }
+
         return result;
     }
 

package/infrastructure/domains/shared/types/app-definition.js

@@ -55,10 +55,26 @@
  *
  * @property {Object} [config] - Configuration preferences
  * @property {'aurora-postgresql'|'aurora-mysql'} [config.engine] - Database engine
- * @property {number} [config.minCapacity] - Min serverless capacity (default: 0.5)
- * @property {number} [config.maxCapacity] - Max serverless capacity (default: 1)
+ * @property {number} [config.minCapacity] - Min serverless capacity in ACU. Accepts
+ *   `0` for Aurora Serverless v2 scale-to-zero (cluster pauses to 0 ACU when idle;
+ *   requires Aurora PostgreSQL 13.15+/14.12+/15.7+/16.3+, and the default 15.13
+ *   qualifies) OR a value in [0.5, 128]. Values in (0, 0.5) are invalid. (default: 0.5)
+ * @property {number} [config.maxCapacity] - Max serverless capacity in ACU, range
+ *   [0.5, 128] (default: 4)
+ * @property {number} [config.secondsUntilAutoPause] - Idle window before a
+ *   scale-to-zero cluster (minCapacity: 0) pauses to 0 ACU. Integer seconds in
+ *   [300, 86400]. Only applied when minCapacity === 0 (default: 300)
  * @property {string} [config.database] - Database name (default: 'frigg')
  * @property {boolean} [config.publiclyAccessible] - Public access (default: false)
+ * @property {'vpc'|'public'} [config.connectivity] - Lambda↔Aurora connectivity
+ *   mode. `'vpc'` (default): Aurora in private subnets, Lambda attached to the VPC,
+ *   ingress from the Lambda security group (needs a NAT for external egress).
+ *   `'public'` (NAT-free): Aurora in public subnets with a public endpoint, Lambda
+ *   left OUTSIDE the VPC (no NAT Gateway, no VPC endpoints), ingress opened to
+ *   `allowedCidrs`, TLS enforced (sslmode=require). (default: 'vpc')
+ * @property {string[]} [config.allowedCidrs] - CIDR blocks allowed to reach Aurora
+ *   on 5432 when connectivity is 'public'. One ingress rule is emitted per CIDR.
+ *   (default: ['0.0.0.0/0'] — narrow this for production)
  * @property {boolean} [config.autoCreateCredentials] - Auto-create credentials in Secrets Manager
  */
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0--canary.629.1a7ad06.0",
+  "version": "2.0.0--canary.640.b31eb4a.0",
   "bin": {
     "frigg": "./frigg-cli/index.js"
   },
@@ -26,9 +26,9 @@
     "@babel/eslint-parser": "^7.18.9",
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
-    "@friggframework/core": "2.0.0--canary.629.1a7ad06.0",
-    "@friggframework/schemas": "2.0.0--canary.629.1a7ad06.0",
-    "@friggframework/test": "2.0.0--canary.629.1a7ad06.0",
+    "@friggframework/core": "2.0.0--canary.640.b31eb4a.0",
+    "@friggframework/schemas": "2.0.0--canary.640.b31eb4a.0",
+    "@friggframework/test": "2.0.0--canary.640.b31eb4a.0",
     "@hapi/boom": "^10.0.1",
     "@inquirer/prompts": "^5.3.8",
     "axios": "^1.18.0",
@@ -56,8 +56,8 @@
     "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0--canary.629.1a7ad06.0",
-    "@friggframework/prettier-config": "2.0.0--canary.629.1a7ad06.0",
+    "@friggframework/eslint-config": "2.0.0--canary.640.b31eb4a.0",
+    "@friggframework/prettier-config": "2.0.0--canary.640.b31eb4a.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
     "jest": "^30.1.3",
@@ -89,5 +89,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "1a7ad067d7f61e2afca452d66706665c7c15b926"
+  "gitHead": "b31eb4a3ddaeae1044d98050b6a436f6d9c08db6"
 }