@venturekit/infra 0.0.0-dev.20260514025219 → 0.0.0-dev.20260515022321

package/dist/cdk/messaging-stack.js

@@ -0,0 +1,320 @@
+/**
+ * Tier 4 — Messaging stack.
+ *
+ * Owns the durable, persistent message-routing infrastructure. By
+ * design every resource here can outlive an app-stack tear-down:
+ * after `vk deploy` rebuilds the app stack, the new consumer
+ * Lambdas pick up exactly where the old ones left off because the
+ * queue + its in-flight messages survived.
+ *
+ * Resources:
+ *
+ *   - One `AWS::SQS::Queue` + matching DLQ per `queues[]` intent.
+ *     Encryption SQS_MANAGED, RETAIN under strict.
+ *   - One Notify pipeline per `notify[]` intent:
+ *       - SNS events topic (SES configuration-set destination)
+ *       - SES `EmailIdentity` (domain or single-address)
+ *       - Optional Route53 DKIM CNAMEs when `hostedZoneId` is set
+ *       - SES `ConfigurationSet` + `EventDestination` publishing
+ *         to the SNS topic
+ *       - WhatsApp Cloud API token Secrets Manager placeholder
+ *         when `'whatsapp'` is in `channels`
+ *       - Two dedicated DLQs: dispatcher-DLQ and bounce-DLQ. The
+ *         consumer Lambdas live in the app stack but their
+ *         on-failure DLQs need RETAIN-class durability so
+ *         operators can drain them on the rare delivery failure.
+ *
+ * # Lifecycle position
+ *
+ * Updated occasionally (~monthly): a new queue, a notify-channel
+ * toggle, a domain rotation. The contents (in-flight messages)
+ * are operationally critical — losing a queue with N messages in
+ * flight is a permanent message loss event. Both `DeletionPolicy:
+ * Retain` and AWS's lack of a queue-level "deletion protection"
+ * flag mean RETAIN is the only durability lever; we set it
+ * unconditionally under strict dataSafety.
+ *
+ * # Public surface (via SSM)
+ *
+ *   - `messagingKeys.queueArn / queueUrl / queueDlqArn /
+ *     queueVisibilityTimeoutSeconds` per `queues[]` intent
+ *   - `messagingKeys.notifyDispatcherDlqArn /
+ *     notifyBounceDlqArn` per `notify[]` intent
+ *   - `configKeys.notifyEventsTopicArn /
+ *     notifyConfigurationSetName / whatsappTokenSecretArn` per
+ *     notify intent. (These straddle the messaging-vs-config
+ *     boundary in the SSM key namespace because the operator pastes
+ *     the WhatsApp token by hand and the SES configuration-set name
+ *     is operator-facing identity, not just plumbing — but they're
+ *     created here because they're inseparable from the SES /
+ *     SNS topology.)
+ *
+ * # What this stack does NOT do
+ *
+ * - **No consumer Lambdas, no event-source mappings.** The Lambda
+ *   that pulls from the queue lives in the app stack. The ESM
+ *   binding it to the queue ALSO lives in the app stack — that
+ *   way an app-stack redeploy can re-create the ESM cleanly without
+ *   touching the persistent queue, which is the whole point of the
+ *   split.
+ *
+ * - **No EventBridge `Rule`s.** Schedules + their Lambda targets
+ *   stay together in the app stack — the Rule + the Lambda are
+ *   inseparable by CDK's permission-grant mechanism, and a Rule on
+ *   its own (with no targets) is dead infrastructure.
+ *
+ * - **No IAM grants.** App-stack Lambda-role wiring grants
+ *   `sqs:SendMessage` / `sqs:ReceiveMessage` / `sns:Publish` /
+ *   `ses:SendEmail` etc. on the imported messaging-tier resources.
+ *
+ * # Why the dispatcher / bounce DLQs live HERE not in the app stack
+ *
+ * Two reasons:
+ *
+ *   1. They're long-lived diagnostic surfaces. An app-stack
+ *      redeploy that drops them means losing every accumulated
+ *      delivery-failure record, which is exactly when the operator
+ *      needs them most.
+ *   2. They're tier-stable. The dispatcher Lambda might rev
+ *      monthly; its DLQ doesn't.
+ */
+import * as cdk from 'aws-cdk-lib';
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+import * as sns from 'aws-cdk-lib/aws-sns';
+import * as ses from 'aws-cdk-lib/aws-ses';
+import * as route53 from 'aws-cdk-lib/aws-route53';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import { DATA_SAFETY_CONFIG } from '@venturekit/core';
+import { writeSsm } from './shared/cross-stack-refs.js';
+import { messagingKeys, configKeys } from './shared/ssm-keys.js';
+export class VentureMessagingStack extends cdk.Stack {
+    queues = new Map();
+    notifyEventsTopics = new Map();
+    notifyDispatcherDlqs = new Map();
+    notifyBounceDlqs = new Map();
+    whatsappTokenSecrets = new Map();
+    isStrictRetain;
+    removalPolicy;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const { projectName, stage, envConfig, infrastructure } = props;
+        this.isStrictRetain = DATA_SAFETY_CONFIG[envConfig.dataSafety].removalPolicy === 'retain';
+        this.removalPolicy = this.isStrictRetain ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY;
+        if (infrastructure.queues) {
+            for (const intent of infrastructure.queues) {
+                this.createQueue(intent, projectName, stage);
+            }
+        }
+        if (infrastructure.notify) {
+            for (const intent of infrastructure.notify) {
+                this.createNotify(intent, projectName, stage);
+            }
+        }
+    }
+    // ─── SQS ─────────────────────────────────────────────────────────────
+    createQueue(intent, projectName, stage) {
+        const logicalId = `queue-${intent.id}`;
+        const fifoSuffix = intent.type === 'fifo' ? '.fifo' : '';
+        // The DLQ name is suffixed `-dlq`; under FIFO both queues need
+        // the `.fifo` suffix and FIFO=true.
+        const dlq = new sqs.Queue(this, `${logicalId}-dlq`, {
+            queueName: `${projectName}-${intent.id}-dlq-${stage}${fifoSuffix}`,
+            fifo: intent.type === 'fifo',
+            retentionPeriod: cdk.Duration.days(14),
+            encryption: sqs.QueueEncryption.SQS_MANAGED,
+            // DLQs are the durable record of every message a consumer
+            // failed to process. CDK's default removalPolicy for sqs.Queue
+            // is DESTROY; under strict dataSafety we promote to RETAIN so
+            // post-incident investigation survives any redeploy.
+            removalPolicy: this.removalPolicy,
+        });
+        // Visibility timeout: explicit `visibilityTimeoutSeconds` wins,
+        // otherwise compute as 6×handler-timeout (AWS recommended floor
+        // for the consumer-Lambda path). The 30s default `intent.timeout`
+        // produces 180s VTO, which is plenty of headroom for handlers
+        // that occasionally spike.
+        const visibilityTimeoutSeconds = intent.visibilityTimeoutSeconds
+            ?? (intent.timeout ?? 30) * 6;
+        const queue = new sqs.Queue(this, logicalId, {
+            queueName: `${projectName}-${intent.id}-${stage}${fifoSuffix}`,
+            fifo: intent.type === 'fifo',
+            visibilityTimeout: cdk.Duration.seconds(visibilityTimeoutSeconds),
+            retentionPeriod: cdk.Duration.days(intent.retentionDays ?? 4),
+            encryption: sqs.QueueEncryption.SQS_MANAGED,
+            deadLetterQueue: {
+                queue: dlq,
+                maxReceiveCount: intent.maxReceiveCount ?? 3,
+            },
+            // Same RETAIN rationale as the DLQ. With messaging in its own
+            // stack, RETAIN means the queue + every in-flight message
+            // survives even an app-stack tear-down — the new app-stack's
+            // ESM picks up where the old one left off.
+            removalPolicy: this.removalPolicy,
+        });
+        this.queues.set(intent.id, { queue, dlq });
+        writeSsm(this, messagingKeys.queueArn(projectName, stage, intent.id), queue.queueArn, {
+            description: `SQS queue ARN for '${intent.id}' — IAM scoping target.`,
+        });
+        writeSsm(this, messagingKeys.queueUrl(projectName, stage, intent.id), queue.queueUrl, {
+            description: `SQS queue URL — what SendMessage callers need.`,
+        });
+        writeSsm(this, messagingKeys.queueDlqArn(projectName, stage, intent.id), dlq.queueArn, {
+            description: `Dead-letter queue ARN for '${intent.id}'.`,
+        });
+        writeSsm(this, messagingKeys.queueVisibilityTimeoutSeconds(projectName, stage, intent.id), String(visibilityTimeoutSeconds), {
+            description: `Primary queue VTO seconds. App stack reads this to enforce ` +
+                `the 'queue.visibilityTimeout >= 6 * fn.timeout' invariant ` +
+                `at synth time when the queue lives in another stack.`,
+        });
+    }
+    // ─── Notify (SES + SNS + WhatsApp + DLQs) ────────────────────────────
+    createNotify(intent, projectName, stage) {
+        const logicalId = `notify-${intent.id}`;
+        const channels = Array.isArray(intent.channels) ? intent.channels : [];
+        const configurationSetName = intent.configurationSetName ?? `${projectName}-${stage}-notify-${intent.id}`;
+        // ── SNS events topic ─────────────────────────────────────────
+        // Receives every SES event for this configuration set. Subscribed
+        // by the bounce-handler Lambda (in app stack) and optionally by
+        // operator-attached observability tools. We don't pin a CMK —
+        // AWS-managed encryption is fine for events that contain at most
+        // recipient PII, and a per-topic CMK would add cost + key-policy
+        // maintenance for no operational benefit.
+        const eventsTopic = new sns.Topic(this, `${logicalId}-events`, {
+            topicName: `${projectName}-${stage}-notify-${intent.id}-events`,
+            displayName: `VentureKit notify events for ${intent.id} (${stage})`,
+        });
+        if (this.isStrictRetain) {
+            const cfn = eventsTopic.node.defaultChild;
+            cfn.cfnOptions.deletionPolicy = cdk.CfnDeletionPolicy.RETAIN;
+            cfn.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+        }
+        this.notifyEventsTopics.set(intent.id, eventsTopic);
+        writeSsm(this, configKeys.notifyEventsTopicArn(projectName, stage, intent.id), eventsTopic.topicArn, { description: `SES events SNS topic for notify '${intent.id}'.` });
+        // ── SES email identity ───────────────────────────────────────
+        if (intent.domain) {
+            const domainIdentity = new ses.EmailIdentity(this, `${logicalId}-domain`, {
+                identity: ses.Identity.domain(intent.domain),
+                dkimSigning: true,
+                // Bounce/complaint feedback flows through the configuration
+                // set event destination instead — no need for SES to forward
+                // every bounce to the operator's inbox.
+                feedbackForwarding: false,
+            });
+            // CDK exposes the three DKIM token pairs as discrete fields,
+            // not arrays. Tuple them so the loop below can stay uniform.
+            const dkimTokens = [
+                { name: domainIdentity.dkimDnsTokenName1, value: domainIdentity.dkimDnsTokenValue1 },
+                { name: domainIdentity.dkimDnsTokenName2, value: domainIdentity.dkimDnsTokenValue2 },
+                { name: domainIdentity.dkimDnsTokenName3, value: domainIdentity.dkimDnsTokenValue3 },
+            ];
+            if (intent.hostedZoneId) {
+                // Auto-publish the three DKIM CNAMEs when we own the zone.
+                // Route53 charges $0.50/zone + $0.40/M queries — these
+                // records are queried only by SES so the cost is negligible.
+                const zone = route53.HostedZone.fromHostedZoneAttributes(this, `${logicalId}-zone`, { hostedZoneId: intent.hostedZoneId, zoneName: intent.domain });
+                dkimTokens.forEach((tok, i) => {
+                    new route53.CnameRecord(this, `${logicalId}-dkim-record-${i + 1}`, {
+                        zone,
+                        // SES tokens are unqualified labels; Route53 appends the
+                        // zone automatically when `recordName` is unqualified.
+                        recordName: `${tok.name}._domainkey`,
+                        domainName: `${tok.value}.dkim.amazonses.com`,
+                        ttl: cdk.Duration.minutes(5),
+                    });
+                });
+            }
+            // When `hostedZoneId` is unset, the operator must publish the
+            // three DKIM CNAMEs themselves. We surface the values via SSM
+            // (under a doc-only key) on a future iteration; today the
+            // operator reads them from `aws ses describe-email-identity`.
+        }
+        else if (intent.defaultFrom) {
+            new ses.EmailIdentity(this, `${logicalId}-email`, {
+                identity: ses.Identity.email(intent.defaultFrom),
+                // Single-address identities don't support DKIM (SES requires
+                // a verified domain for that).
+                feedbackForwarding: false,
+            });
+        }
+        else {
+            throw new Error(`[venturekit] notify intent '${intent.id}' must declare either ` +
+                `'defaultFrom' (single-address SES identity) or 'domain' (DomainIdentity).`);
+        }
+        // ── Configuration set + event destination ────────────────────
+        const configSet = new ses.ConfigurationSet(this, `${logicalId}-config-set`, {
+            configurationSetName,
+            sendingEnabled: true,
+            // Reputation metrics surface deliverability stats in CloudWatch
+            // — free, useful for operators chasing soft-bounce rates.
+            reputationMetrics: true,
+            tlsPolicy: ses.ConfigurationSetTlsPolicy.REQUIRE,
+        });
+        new ses.ConfigurationSetEventDestination(this, `${logicalId}-event-dest`, {
+            configurationSet: configSet,
+            destination: ses.EventDestination.snsTopic(eventsTopic),
+            // Subscribe to bounce/complaint always (suppression logic
+            // depends on them) plus delivery/open/click for observability.
+            // REJECT is implicit — SES throws synchronously and the
+            // dispatcher captures it without an event.
+            events: [
+                ses.EmailSendingEvent.SEND,
+                ses.EmailSendingEvent.REJECT,
+                ses.EmailSendingEvent.BOUNCE,
+                ses.EmailSendingEvent.COMPLAINT,
+                ses.EmailSendingEvent.DELIVERY,
+                ses.EmailSendingEvent.OPEN,
+                ses.EmailSendingEvent.CLICK,
+            ],
+            enabled: true,
+        });
+        writeSsm(this, configKeys.notifyConfigurationSetName(projectName, stage, intent.id), configurationSetName, { description: `SES configuration set name — every SendEmail uses it.` });
+        // ── WhatsApp token secret ────────────────────────────────────
+        if (channels.includes('whatsapp')) {
+            if (!intent.whatsapp?.phoneNumberId) {
+                throw new Error(`[venturekit] notify intent '${intent.id}' has 'whatsapp' channel ` +
+                    `but no 'whatsapp.phoneNumberId'. Set it from Meta Business Suite ` +
+                    `→ WhatsApp → API Setup.`);
+            }
+            const secret = new secretsmanager.Secret(this, `${logicalId}-whatsapp-token`, {
+                secretName: `venturekit/${projectName}/${stage}/notify-${intent.id}-whatsapp-token`,
+                description: `Meta WhatsApp Cloud API access token for notify '${intent.id}'. ` +
+                    `Set the value via the Secrets Manager console after first deploy.`,
+                secretStringValue: cdk.SecretValue.unsafePlainText('PLACEHOLDER_SET_VALUE_AFTER_DEPLOY'),
+                removalPolicy: this.removalPolicy,
+            });
+            if (this.isStrictRetain) {
+                const cfn = secret.node.defaultChild;
+                cfn.cfnOptions.updateReplacePolicy = cdk.CfnDeletionPolicy.RETAIN;
+            }
+            this.whatsappTokenSecrets.set(intent.id, secret);
+            writeSsm(this, configKeys.whatsappTokenSecretArn(projectName, stage, intent.id), secret.secretArn, {
+                description: `WhatsApp token Secret ARN. Operators populate via ` +
+                    `'aws secretsmanager put-secret-value'.`,
+            });
+        }
+        // ── Dispatcher + bounce DLQs ─────────────────────────────────
+        // The dispatcher Lambda (cron-triggered, drains the outbox table
+        // and pushes through SES/WhatsApp) and the bounce-handler Lambda
+        // (subscribed to the SNS events topic) both live in the app stack.
+        // Their on-failure DLQs live HERE because they accumulate
+        // diagnostic records across redeploys; losing them is exactly
+        // what RETAIN is for.
+        const dispatcherDlq = new sqs.Queue(this, `${logicalId}-dispatcher-dlq`, {
+            queueName: `${projectName}-${stage}-notify-${intent.id}-dispatcher-dlq`,
+            retentionPeriod: cdk.Duration.days(14),
+            encryption: sqs.QueueEncryption.SQS_MANAGED,
+            removalPolicy: this.removalPolicy,
+        });
+        const bounceDlq = new sqs.Queue(this, `${logicalId}-bounce-dlq`, {
+            queueName: `${projectName}-${stage}-notify-${intent.id}-bounce-dlq`,
+            retentionPeriod: cdk.Duration.days(14),
+            encryption: sqs.QueueEncryption.SQS_MANAGED,
+            removalPolicy: this.removalPolicy,
+        });
+        this.notifyDispatcherDlqs.set(intent.id, dispatcherDlq);
+        this.notifyBounceDlqs.set(intent.id, bounceDlq);
+        writeSsm(this, messagingKeys.notifyDispatcherDlqArn(projectName, stage, intent.id), dispatcherDlq.queueArn, { description: `Dispatcher Lambda on-failure DLQ ARN.` });
+        writeSsm(this, messagingKeys.notifyBounceDlqArn(projectName, stage, intent.id), bounceDlq.queueArn, { description: `Bounce-handler Lambda on-failure DLQ ARN.` });
+    }
+}
+//# sourceMappingURL=messaging-stack.js.map

package/dist/cdk/messaging-stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging-stack.js","sourceRoot":"","sources":["../../src/cdk/messaging-stack.ts"],"names":[],"mappings":"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"}

package/dist/cdk/network-stack.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Tier 0 — Network stack.
+ *
+ * Owns: VPC, all subnets (public / private-with-egress / isolated),
+ * NAT gateways or fck-nat instances, route tables, the gateway VPC
+ * endpoints (S3, DynamoDB), the optional interface endpoints
+ * (Secrets Manager — by default off until preset opts in), and the
+ * VPC flow log destination.
+ *
+ * # Lifecycle position
+ *
+ * Updated almost never (~once a year, when AWS rolls a new fck-nat
+ * AMI or the operator adds an AZ). Survives stack delete because
+ * everything is RETAIN. The data tier (RDS in private subnets) and
+ * the app tier (Lambdas in private subnets) both depend on the
+ * network tier's published surface; deleting the network stack
+ * orphans every subnet ID + VPC ID — recoverable via `cdk import`,
+ * never automatic.
+ *
+ * # Public surface (via SSM)
+ *
+ * Published exclusively under `networkKeys` in `shared/ssm-keys.ts`:
+ *
+ *   - `vpcId` — the singular VPC ID
+ *   - `availabilityZones` — comma-joined, ordered
+ *   - `privateSubnetIds`, `publicSubnetIds`, `isolatedSubnetIds` —
+ *     comma-joined, ordered to match `availabilityZones`
+ *
+ * That's it. Consumers never reach in for individual subnets, NAT
+ * IDs, or route table IDs — those are private to this stack.
+ *
+ * # Why no exports?
+ *
+ * `cdk.CfnOutput` + `Fn::ImportValue` carries CFN's "consumed export
+ * cannot be modified" lock. SSM dynamic references don't. See the
+ * long-form rationale in `shared/ssm-keys.ts`.
+ *
+ * # Free-tier handling
+ *
+ * On the `free` preset, no VPC is provisioned at all (the preset
+ * runs DynamoDB + storage-only Lambdas with no in-VPC dependencies,
+ * which keeps the deploy at $0/month). The CLI's stack generator
+ * therefore must not instantiate `VentureNetworkStack` when the
+ * preset resolves to `free` AND no intent demands a VPC. This stack
+ * itself never inspects the preset — it always provisions a VPC
+ * when constructed. The instantiation gate lives in the generator.
+ */
+import * as cdk from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { Construct } from 'constructs';
+import { type EnvConfig } from '@venturekit/core';
+export interface VentureNetworkStackProps extends cdk.StackProps {
+    /**
+     * Project name — fed into every resource name and every SSM key
+     * for tenant isolation across multi-project AWS accounts.
+     */
+    projectName: string;
+    /** Stage / well-known env (`dev` | `stage` | `prod` | …). */
+    stage: string;
+    /**
+     * Fully-resolved environment config from
+     * `resolveEnvConfig(stage, { preset })`. The network stack reads
+     * `vpc.*` (CIDR, subnet masks, NAT type, AZ count, endpoint
+     * toggles) and `dataSafety` (drives `removalPolicy` on the flow
+     * log group).
+     */
+    envConfig: EnvConfig;
+}
+export declare class VentureNetworkStack extends cdk.Stack {
+    /**
+     * In-process VPC reference for sibling stacks deployed in the
+     * same `cdk.App` (the standard `cdk deploy --all` case). Sibling
+     * stacks that take a direct CDK reference avoid one round-trip
+     * through SSM at synth time and get full CDK-typed access to the
+     * VPC abstraction, including AZ + subnet ordering.
+     *
+     * Cross-deploy and cross-account consumers must instead read the
+     * SSM parameters and reconstruct via `importVpc` from
+     * `shared/cross-stack-refs.ts` — that path uses
+     * `Vpc.fromVpcAttributes` which has slightly fewer affordances
+     * than the live reference (no `.selectSubnets({ subnetGroupName })`,
+     * for example).
+     */
+    readonly vpc: ec2.Vpc;
+    constructor(scope: Construct, id: string, props: VentureNetworkStackProps);
+}
+//# sourceMappingURL=network-stack.d.ts.map

package/dist/cdk/network-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-stack.d.ts","sourceRoot":"","sources":["../../src/cdk/network-stack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAItE,MAAM,WAAW,wBAAyB,SAAQ,GAAG,CAAC,UAAU;IAC9D;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,SAAS,EAAE,SAAS,CAAC;CACtB;AAwBD,qBAAa,mBAAoB,SAAQ,GAAG,CAAC,KAAK;IAChD;;;;;;;;;;;;;OAaG;IACH,SAAgB,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;gBAEjB,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,wBAAwB;CAwM1E"}