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

package/dist/cdk/app-stack.js

@@ -0,0 +1,875 @@
+/**
+ * Tier 6 — App stack (the "fast" tier).
+ *
+ * Owns every resource that turns over on a normal `vk deploy`:
+ *
+ *   - Lambda functions: route handlers, queue consumers, scheduled
+ *     handlers, notify dispatcher, bounce handler, migration runner.
+ *   - HttpApi route/integration registrations on the imported API.
+ *   - SQS event-source mappings binding consumer Lambdas to
+ *     queues imported from the messaging stack.
+ *   - EventBridge rules + Lambda targets for `schedules[]` intents
+ *     and the notify dispatcher cron.
+ *   - Per-Lambda CloudWatch LogGroups (so retention is enforced
+ *     even on cold-start failures, before the runtime can write
+ *     its first line).
+ *   - Shared Lambda execution role + shared SG (in VPC) — the
+ *     common identity through which every grant is plumbed.
+ *   - Internal HMAC secret for Lambda-to-Lambda `invoke()` signing.
+ *   - All IAM grants: Cognito admin, S3 R/W, Secrets Manager
+ *     reads, SES send, SQS consume/produce, SNS publish.
+ *
+ * # Lifecycle position
+ *
+ * Updated on every code change (~daily on active projects). Every
+ * resource here is DESTROY-on-delete: re-creating a Lambda or an
+ * ESM from a saved CFN template is cheap and safe (the durable
+ * state — DB rows, queue messages, S3 objects — lives in
+ * lower-tier stacks). Logs are an exception: under strict
+ * dataSafety we RETAIN log groups so post-mortem debugging
+ * survives a redeploy.
+ *
+ * # What the constructor does (in order)
+ *
+ *   1. Resolve cross-stack refs from imported props or via SSM.
+ *   2. Create shared Lambda execution role + (if VPC) shared SG.
+ *   3. Generate / import the internal HMAC secret.
+ *   4. Assemble `baseEnvVars` from cross-tier SSM-resolved values:
+ *      DB connection, primary storage, primary notify, Cognito,
+ *      federated provider secrets.
+ *   5. Wire each Lambda intent (delegated to step-9b/c/d helpers
+ *      that follow this scaffold).
+ *
+ * # Why the role + SG live in this stack
+ *
+ * They're scoped to "the Lambdas in this app deployment" — every
+ * grant attached to them is therefore lifecycle-aligned with the
+ * Lambdas. A redeploy that adds a new managed policy or a new
+ * `addPermission` call only churns the app stack; the lower-tier
+ * resources stay untouched.
+ *
+ * # What this stack does NOT do
+ *
+ * - **No durable state.** Every resource here is replaceable.
+ *   If you need RETAIN-class durability, the resource belongs in
+ *   data / messaging / identity / config / edge.
+ *
+ * - **No HttpApi creation.** Imported via
+ *   `HttpApi.fromHttpApiAttributes` from the edge stack's published
+ *   `apiId` SSM key.
+ *
+ * - **No SSM publication.** App-stack outputs (Lambda ARNs, log
+ *   group names) are operational details that no other VentureKit
+ *   stack consumes. Operators inspecting them go through the AWS
+ *   console / CLI, not SSM.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createRequire } from 'module';
+import * as cdk from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as lambdaEventSources from 'aws-cdk-lib/aws-lambda-event-sources';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+import * as events from 'aws-cdk-lib/aws-events';
+import * as eventsTargets from 'aws-cdk-lib/aws-events-targets';
+import * as apigatewayv2 from 'aws-cdk-lib/aws-apigatewayv2';
+import * as apigatewayv2Integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import * as sns from 'aws-cdk-lib/aws-sns';
+import * as snsSubscriptions from 'aws-cdk-lib/aws-sns-subscriptions';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import * as logs from 'aws-cdk-lib/aws-logs';
+import { DATA_SAFETY_CONFIG, } from '@venturekit/core';
+import { readSsmString } from './shared/cross-stack-refs.js';
+import { networkKeys, edgeKeys } from './shared/ssm-keys.js';
+import { bundleHandlerCodeWithEsbuild, inlineStubLambdaCode, toLambdaArchitecture, toLambdaRuntime, toLogRetention, clampLambdaFunctionName, discoverFunctionFiles, } from './shared/lambda-helpers.js';
+import { discoverRouteFiles } from './stack.js';
+/**
+ * Convert an intent id (e.g. `user-uploads`) to upper-snake-case
+ * (`USER_UPLOADS`) suitable for use in env-var names. Without this,
+ * a hyphenated id would produce `STORAGE_user-uploads_BUCKET`,
+ * which CloudFormation rejects.
+ */
+function upperSnake(id) {
+    return String(id).toUpperCase().replace(/[^A-Z0-9_]/g, '_');
+}
+/**
+ * App stack — see file header for the full lifecycle rationale.
+ *
+ * **Step 9a scaffold.** This skeleton covers:
+ *   - shared Lambda role + (if VPC) shared SG
+ *   - imported HttpApi + VPC handles exposed for sub-step helpers
+ *   - internal HMAC secret
+ *   - `baseEnvVars` assembled from cross-stack imports
+ *
+ * Lambda creation lives in subsequent sub-steps (9b: routes;
+ * 9c: queue ESMs + schedules + migration; 9d: notify + grants).
+ * Calling the constructor with no Lambda-bearing intents produces
+ * a stack with the role / SG / secret only — no Lambdas, no
+ * routes — which is the correct no-op behavior for projects that
+ * declare only data + messaging.
+ */
+export class VentureAppStack extends cdk.Stack {
+    /** Shared execution role for every Lambda in this stack. */
+    lambdaRole;
+    /** Shared SG when a VPC is imported; undefined for VPC-less projects. */
+    lambdaSecurityGroup;
+    /** Internal HMAC signing secret for Lambda-to-Lambda `invoke()`. */
+    internalHmacSecret;
+    /**
+     * Base environment variables applied to every Lambda this stack
+     * creates. Subsequent helpers (9b/c/d) read this when constructing
+     * each Lambda's `environment` block. Mutable during construction
+     * — per-intent helpers append `STORAGE_<ID>_*`, `NOTIFY_<ID>_*`,
+     * etc. — frozen at the end of the constructor.
+     */
+    baseEnvVars;
+    /** The imported HttpApi — sub-step 9b registers routes on this. */
+    api;
+    /** Imported VPC, when present. */
+    vpc;
+    /**
+     * Route Lambdas keyed by slug. Sub-step 9c reads this when wiring
+     * cross-cutting grants (e.g. Cognito admin auth) onto every
+     * Lambda — though the shared role makes most grants role-level
+     * not function-level, this map lets per-function grants happen
+     * when needed.
+     */
+    routeLambdas = new Map();
+    /** Queue consumer Lambdas keyed by handler name. */
+    queueLambdas = new Map();
+    /** Scheduled / cron Lambdas keyed by handler name. */
+    scheduleLambdas = new Map();
+    /** Notify dispatcher Lambdas keyed by notify intent id. */
+    notifyDispatcherLambdas = new Map();
+    /** Notify bounce-handler Lambdas keyed by notify intent id. */
+    notifyBounceLambdas = new Map();
+    isStrictRetain;
+    projectName;
+    stage;
+    envConfig;
+    skipBundling;
+    projectDir;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const { projectName, stage, envConfig, infrastructure, imports } = props;
+        this.isStrictRetain =
+            DATA_SAFETY_CONFIG[envConfig.dataSafety].removalPolicy === 'retain';
+        this.vpc = imports.vpc;
+        this.api = imports.api;
+        this.projectName = projectName;
+        this.stage = stage;
+        this.envConfig = envConfig;
+        this.skipBundling = props.skipBundling ?? false;
+        this.projectDir = props.projectDir;
+        // ─── Lambda count probe ────────────────────────────────────
+        // Detect whether this deployment includes any Lambda-bearing
+        // intent. If not, we still create the role + secret + base env
+        // (cheap, static) so the stack is consistent across deploys —
+        // but we skip the SG (which only makes sense with Lambdas in a
+        // VPC). The probe is intentionally permissive: any of
+        // functions / queues / schedules / notify triggers it.
+        // Routes and migrations are discovered from the filesystem
+        // (see route discovery below and `hasMigrations(dbDir)` in
+        // `stack.ts`); fold them in here when this probe is wired up
+        // to gate SG creation.
+        const hasAnyLambda = Boolean(infrastructure.functions) ||
+            Boolean(infrastructure.queues) ||
+            Boolean(infrastructure.schedules) ||
+            Boolean(infrastructure.notify);
+        // ─── Shared Lambda execution role ──────────────────────────
+        this.lambdaRole = new iam.Role(this, 'LambdaRole', {
+            assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+            description: `Shared execution role for ${projectName}-${stage} Lambdas`,
+            managedPolicies: [
+                iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
+            ],
+        });
+        if (this.vpc) {
+            // VPC-attached Lambdas need ENI-creation rights on cold start.
+            // Bolted on conditionally so VPC-less projects don't carry the
+            // unused managed policy.
+            this.lambdaRole.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'));
+            this.lambdaSecurityGroup = new ec2.SecurityGroup(this, 'LambdaSg', {
+                vpc: this.vpc,
+                description: `Shared SG for ${projectName}-${stage} Lambdas`,
+                // Outbound open to anywhere — Lambdas in private subnets reach
+                // the internet through the VPC NAT, and reach AWS services
+                // through interface endpoints. Restricting outbound at SG level
+                // breaks legitimate egress (DB, AWS APIs, third-party APIs)
+                // without meaningfully tightening security; the firewall is
+                // the network ACL on the subnet, not the SG.
+                allowAllOutbound: true,
+            });
+            // DB ingress rules from the shared Lambda SG to each declared
+            // database SG live HERE because they're scoped to "Lambdas
+            // talking to DBs" — pure app-tier wiring. The lower-tier
+            // network/data stacks own the SGs themselves; this stack
+            // contributes only the ingress permission.
+            //
+            // Implementation deferred to sub-step 9c (alongside ESM wiring
+            // — both sets of grants share the same iteration over
+            // `infrastructure.databases[]`).
+        }
+        // ─── Internal HMAC secret ──────────────────────────────────
+        // Per-project HMAC key for signing internal Lambda-to-Lambda
+        // calls (see `@venturekit/runtime/invoke`). CloudFormation auto-
+        // generates the value on first deploy and preserves it across
+        // stack updates — so warm Lambdas don't lose trust on every
+        // redeploy. The VALUE is injected as an env var (not the ARN),
+        // so handlers don't pay an SDK round-trip per cold start.
+        //
+        // Lifecycle: this secret IS app-tier — its lifetime is tied to
+        // the Lambdas that consume it, and rotating it would require a
+        // coordinated Lambda rollout anyway. RETAIN under strict isn't
+        // appropriate; on a stack delete we're tearing down every Lambda
+        // that uses the key, so retaining the key alone serves no purpose.
+        this.internalHmacSecret = new secretsmanager.Secret(this, 'internalHmacSecret', {
+            secretName: `venturekit/${projectName}/${stage}/internal-hmac`,
+            description: 'VentureKit internal Lambda-to-Lambda HMAC signing key. Auto-generated.',
+            generateSecretString: {
+                // 64 hex chars = 256 bits. SHA-256 HMAC's natural key size.
+                // `excludePunctuation` keeps the value free of shell
+                // metacharacters when operators copy it for debugging.
+                passwordLength: 64,
+                excludePunctuation: true,
+                // No JSON wrapper — the secret value is read as a raw
+                // string by `@venturekit/runtime/invoke`.
+                generateStringKey: 'value',
+                secretStringTemplate: '{}',
+            },
+        });
+        // ─── Base env-var assembly ─────────────────────────────────
+        // Every Lambda gets these set in its `environment` block. The
+        // record is mutable during the rest of the constructor — sub-
+        // step helpers append per-intent keys (`STORAGE_<ID>_BUCKET`,
+        // `NOTIFY_<ID>_FROM`, etc.) before the first Lambda is created.
+        // Frozen as the very last constructor step (sub-step 9d) so
+        // any post-construct mutation throws.
+        this.baseEnvVars = {
+            VENTURE_PROJECT_NAME: projectName,
+            VENTURE_STAGE: stage,
+            // Inline value, not ARN. Lambdas read it directly from
+            // env without hitting Secrets Manager — zero cold-start cost
+            // for HMAC verification.
+            VENTURE_INTERNAL_HMAC_SECRET: this.internalHmacSecret.secretValue.unsafeUnwrap(),
+            // `--enable-source-maps` makes thrown errors point to the
+            // .ts source instead of bundled .js. Free win in CloudWatch.
+            NODE_OPTIONS: '--enable-source-maps',
+        };
+        // ─── Cross-tier env injection (cheap, static keys only) ────
+        // Per-intent keys go through helpers in sub-steps 9b/c/d. The
+        // ones below are stack-wide singletons — primary DB, primary
+        // storage, primary auth — that can be assembled here without
+        // iterating intents.
+        if (imports.databaseEndpointsById && imports.databaseEndpointsById.size > 0) {
+            // Convention: the FIRST declared `database` intent is the
+            // primary. Operators with multiple DBs (rare) read the per-
+            // intent keys (`DB_<ID>_*`, populated in 9c) instead.
+            const [primaryId, primary] = imports.databaseEndpointsById.entries().next().value;
+            void primaryId;
+            this.baseEnvVars['DB_HOST'] = primary.host;
+            this.baseEnvVars['DB_PORT'] = primary.port;
+            this.baseEnvVars['DB_NAME'] = primary.name;
+            // RDS enforces TLS on every modern engine; flipping this here
+            // means consumers don't have to remember to set it themselves.
+            this.baseEnvVars['DB_SSL'] = 'true';
+            if (primary.secretArn) {
+                this.baseEnvVars['DB_SECRET_ARN'] = primary.secretArn;
+            }
+        }
+        if (imports.storageBucketNamesById && imports.storageBucketNamesById.size > 0) {
+            const [, primaryBucket] = imports.storageBucketNamesById.entries().next().value;
+            this.baseEnvVars['VENTURE_STORAGE_BUCKET'] = primaryBucket;
+        }
+        if (imports.userPoolArnsByAuthId && imports.userPoolArnsByAuthId.size > 0) {
+            // The runtime's `loadAuthServerConfig()` reads
+            // `COGNITO_USER_POOL_ID`. We don't have just the ID here —
+            // ARN format is `arn:aws:cognito-idp:<region>:<acct>:userpool/<id>`,
+            // so we slice it.
+            const [, primaryArn] = imports.userPoolArnsByAuthId.entries().next().value;
+            const idMatch = primaryArn.match(/userpool\/(.+)$/);
+            if (idMatch) {
+                this.baseEnvVars['COGNITO_USER_POOL_ID'] = idMatch[1];
+            }
+        }
+        void hasAnyLambda;
+        void readSsmString;
+        void networkKeys;
+        void edgeKeys;
+        // ─── Per-intent env-var injection (sub-step 9d) ────────────
+        // Sub-step 9a populated PRIMARY-only keys (DB_HOST,
+        // VENTURE_STORAGE_BUCKET, COGNITO_USER_POOL_ID). Per-intent
+        // keys land here so handlers can reference any declared
+        // resource by id without runtime SSM lookups.
+        if (imports.storageBucketNamesById) {
+            for (const [id, bucketName] of imports.storageBucketNamesById) {
+                const idKey = upperSnake(id);
+                this.baseEnvVars[`STORAGE_${idKey}_BUCKET`] = bucketName;
+                const cdnDomain = imports.storageCdnDomainsById?.get(id);
+                if (cdnDomain) {
+                    this.baseEnvVars[`STORAGE_${idKey}_CDN_URL`] = `https://${cdnDomain}`;
+                }
+            }
+            // VENTURE_STORAGE_CDN_URL primary mirror (if the primary has CDN).
+            const [primaryStorageId] = imports.storageBucketNamesById.entries().next().value;
+            const primaryCdn = imports.storageCdnDomainsById?.get(primaryStorageId);
+            if (primaryCdn) {
+                this.baseEnvVars['VENTURE_STORAGE_CDN_URL'] = `https://${primaryCdn}`;
+            }
+        }
+        if (imports.notifyConfigurationSetNamesById) {
+            // Primary notify is the first declared intent.
+            const entries = [...imports.notifyConfigurationSetNamesById.entries()];
+            if (entries.length > 0) {
+                const [primaryId, primaryConfigSet] = entries[0];
+                this.baseEnvVars['VENTURE_NOTIFY_CONFIG_SET'] = primaryConfigSet;
+                const primaryTopicArn = imports.notifyEventsTopicArnsById?.get(primaryId);
+                if (primaryTopicArn) {
+                    this.baseEnvVars['VENTURE_NOTIFY_EVENTS_TOPIC_ARN'] = primaryTopicArn;
+                }
+                const primaryWhatsapp = imports.whatsappTokenSecretArnsById?.get(primaryId);
+                if (primaryWhatsapp) {
+                    this.baseEnvVars['VENTURE_NOTIFY_WHATSAPP_TOKEN_SECRET'] = primaryWhatsapp;
+                }
+            }
+            for (const [id, configSet] of imports.notifyConfigurationSetNamesById) {
+                const idKey = upperSnake(id);
+                this.baseEnvVars[`NOTIFY_${idKey}_CONFIG_SET`] = configSet;
+                const topicArn = imports.notifyEventsTopicArnsById?.get(id);
+                if (topicArn) {
+                    this.baseEnvVars[`NOTIFY_${idKey}_EVENTS_TOPIC_ARN`] = topicArn;
+                }
+            }
+        }
+        // ─── IAM grants on the shared Lambda role ──────────────────
+        // Every grant attached to `this.lambdaRole` benefits every
+        // Lambda in the stack (routes, queue consumers, schedules,
+        // notify dispatcher/bounce). The trade-off documented in
+        // 9a's role rationale: a route Lambda technically has SQS
+        // receive perms even though it never uses them — accepted
+        // because the alternative (one role per Lambda) blows past
+        // CFN's 500-resource limit on large projects.
+        this.applyImportedGrants(imports);
+        // Freeze base env-vars after all per-intent injection. Any
+        // post-construct mutation by a third-party extender (or a
+        // future sub-step that forgets to run before freeze) throws
+        // at runtime instead of silently producing inconsistent
+        // Lambda environments.
+        Object.freeze(this.baseEnvVars);
+        // ─── Route Lambdas + HttpApi route registrations ───────────
+        // Walks `${projectDir}/${routesDir}` and creates one Lambda +
+        // HttpRoute per discovered handler. Skipped silently when no
+        // routes dir exists or no API was imported — the latter would
+        // produce orphan Lambdas with nothing routing to them, which
+        // is never the right outcome.
+        if (props.projectDir) {
+            const resolvedRoutesDir = path.resolve(props.projectDir, props.routesDir ?? 'src/routes');
+            const discoveredRoutes = fs.existsSync(resolvedRoutesDir)
+                ? discoverRouteFiles(resolvedRoutesDir)
+                : [];
+            if (discoveredRoutes.length > 0) {
+                if (!this.api) {
+                    throw new Error(`[venturekit] app stack: ${discoveredRoutes.length} route handler(s) ` +
+                        `discovered under '${resolvedRoutesDir}' but no HttpApi was imported. ` +
+                        `The CLI generator must pass imports.api when route handlers exist. ` +
+                        `(Edge stack publishes apiId via SSM; generator imports via ` +
+                        `HttpApi.fromHttpApiAttributes.)`);
+                }
+                for (const route of discoveredRoutes) {
+                    this.createRouteFunction(route);
+                }
+            }
+            // ─── Queue consumer Lambdas + ESMs ────────────────────────
+            // Each file in `queuesDir` produces one consumer Lambda
+            // bound to a queue imported from the messaging stack via
+            // `imports.queueArnsById`. The queue ID matches the file-
+            // derived handler name (`src/queues/jobs.ts` →
+            // `imports.queueArnsById.get('jobs')`).
+            const resolvedQueuesDir = path.resolve(props.projectDir, props.queuesDir ?? 'src/queues');
+            if (fs.existsSync(resolvedQueuesDir)) {
+                const queueHandlers = discoverFunctionFiles(resolvedQueuesDir);
+                const queueIntents = infrastructure.queues ?? [];
+                for (const qFile of queueHandlers) {
+                    const intent = queueIntents.find((q) => q.id === qFile.name);
+                    this.createQueueConsumer(qFile.name, qFile.handlerFile, intent, imports);
+                }
+            }
+            // ─── Schedule / cron Lambdas + EventBridge rules ─────────
+            // File-discovered from `cronsDir`; the matching
+            // `infrastructure.schedules[]` intent (if any) provides the
+            // schedule expression. Files without a matching intent
+            // create the Lambda but no Rule — the operator can wire
+            // the trigger manually or in a follow-up deploy after
+            // declaring the schedule.
+            const resolvedCronsDir = path.resolve(props.projectDir, props.cronsDir ?? 'src/crons');
+            if (fs.existsSync(resolvedCronsDir)) {
+                const cronHandlers = discoverFunctionFiles(resolvedCronsDir);
+                const scheduleIntents = infrastructure.schedules ?? [];
+                for (const cFile of cronHandlers) {
+                    const intent = scheduleIntents.find((s) => s.id === cFile.name);
+                    this.createScheduleHandler(cFile.name, cFile.handlerFile, intent);
+                }
+            }
+            // ─── Notify dispatcher + bounce-handler Lambdas (9d-2) ────
+            // Each declared `notify[]` intent gets two managed Lambdas:
+            // a cron-driven dispatcher (drains the outbox table → SES /
+            // WhatsApp) and an SNS-subscribed bounce handler. Both
+            // bundle stub modules shipped by `@venturekit/notify`; the
+            // stubs delegate to the operator's notify client module
+            // discovered via project package.json convention.
+            if (infrastructure.notify && infrastructure.notify.length > 0) {
+                this.provisionNotifyHandlers(infrastructure.notify, props.projectDir, imports);
+            }
+        }
+    }
+    /**
+     * Build the Lambda code asset for a handler file. Production path:
+     * esbuild in-process, sub-second per handler. Test path: inline
+     * stub that satisfies API Gateway's contract without invoking
+     * esbuild.
+     */
+    bundleHandlerCode(handlerFile) {
+        if (this.skipBundling)
+            return inlineStubLambdaCode();
+        if (!this.projectDir) {
+            // The constructor only triggers route discovery when
+            // `projectDir` is set, so reaching here implies a future
+            // sub-step (9c/d) that bundles a Lambda without a project
+            // dir — caller bug, not user error.
+            throw new Error(`[venturekit] bundleHandlerCode called without projectDir set. ` +
+                `Set VentureAppStackProps.projectDir or VentureAppStackProps.skipBundling.`);
+        }
+        return bundleHandlerCodeWithEsbuild(handlerFile, this.projectDir);
+    }
+    /**
+     * Materialise one route handler: a Lambda function + an
+     * `HttpRoute` on the imported API + an `HttpLambdaIntegration`
+     * binding them together. CDK's `HttpLambdaIntegration` adds the
+     * `lambda:InvokeFunction` resource policy automatically so the
+     * cross-stack pattern works the same as in-stack.
+     */
+    createRouteFunction(route) {
+        const lambdaConfig = this.envConfig.lambda;
+        const functionName = clampLambdaFunctionName(`${this.projectName}-${this.stage}-route-${route.slug}`);
+        const resourceId = `route-${route.slug}`;
+        const fn = new lambda.Function(this, resourceId, {
+            functionName,
+            runtime: toLambdaRuntime(this.envConfig),
+            architecture: toLambdaArchitecture(this.envConfig),
+            handler: 'index.main',
+            code: this.bundleHandlerCode(route.handlerFile),
+            memorySize: lambdaConfig.memoryMb,
+            timeout: cdk.Duration.seconds(lambdaConfig.timeoutSec),
+            description: `${route.method} ${route.apiPath}`,
+            environment: {
+                ...this.baseEnvVars,
+                ...lambdaConfig.environmentVariables,
+            },
+            // Explicit LogGroup, NOT the deprecated `logRetention` prop.
+            // `logRetention` provisions a stack-wide custom-resource Lambda
+            // (+ its own IAM role) that calls `PutRetentionPolicy` after
+            // every deploy — that helper Lambda counts toward the project's
+            // function quota AND is created lazily on first cold-start
+            // failure of any handler, which is exactly when you DON'T want
+            // a CFN custom-resource invocation. Pre-creating the LogGroup
+            // fixes the retention at synth time and lets us apply RETAIN
+            // under strict dataSafety the same way the rest of this stack
+            // does.
+            logGroup: new logs.LogGroup(this, `${resourceId}-logs`, {
+                logGroupName: `/aws/lambda/${functionName}`,
+                retention: toLogRetention(lambdaConfig.logRetentionDays),
+                removalPolicy: this.isStrictRetain
+                    ? cdk.RemovalPolicy.RETAIN
+                    : cdk.RemovalPolicy.DESTROY,
+            }),
+            tracing: lambdaConfig.tracingEnabled
+                ? lambda.Tracing.ACTIVE
+                : lambda.Tracing.DISABLED,
+            reservedConcurrentExecutions: lambdaConfig.reservedConcurrency,
+            role: this.lambdaRole,
+            // Attach to the VPC iff one exists. Route Lambdas without a VPC
+            // can't reach RDS, but the free preset and DB-less projects
+            // don't need one — paying ENI cold-start tax there would be
+            // a regression.
+            ...(this.vpc && this.lambdaSecurityGroup
+                ? {
+                    vpc: this.vpc,
+                    vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
+                    securityGroups: [this.lambdaSecurityGroup],
+                }
+                : {}),
+        });
+        this.routeLambdas.set(route.slug, fn);
+        // Add the HttpRoute on the imported API. `HttpRouteKey.with`
+        // builds the canonical `${METHOD} ${path}` string AWS uses
+        // internally; passing path + method separately keeps us honest
+        // if AWS ever changes the format.
+        new apigatewayv2.HttpRoute(this, `${resourceId}-route`, {
+            httpApi: this.api,
+            routeKey: apigatewayv2.HttpRouteKey.with(route.apiPath, apigatewayv2.HttpMethod[route.method]),
+            integration: new apigatewayv2Integrations.HttpLambdaIntegration(`${resourceId}-integration`, fn),
+        });
+    }
+    /**
+     * Build a Lambda function with the standard app-stack properties
+     * (shared role, VPC attachment, base env vars, log retention).
+     * Used by `createRouteFunction` (now refactored), `createQueueConsumer`,
+     * and `createScheduleHandler` to keep the per-Lambda invariants in
+     * one place.
+     */
+    buildLambda(resourceId, functionName, handlerFile, description, overrides) {
+        const lambdaConfig = this.envConfig.lambda;
+        return new lambda.Function(this, resourceId, {
+            functionName,
+            runtime: toLambdaRuntime(this.envConfig),
+            architecture: toLambdaArchitecture(this.envConfig),
+            handler: 'index.main',
+            code: this.bundleHandlerCode(handlerFile),
+            memorySize: lambdaConfig.memoryMb,
+            timeout: cdk.Duration.seconds(lambdaConfig.timeoutSec),
+            description,
+            environment: {
+                ...this.baseEnvVars,
+                ...lambdaConfig.environmentVariables,
+            },
+            logGroup: new logs.LogGroup(this, `${resourceId}-logs`, {
+                logGroupName: `/aws/lambda/${functionName}`,
+                retention: toLogRetention(lambdaConfig.logRetentionDays),
+                removalPolicy: this.isStrictRetain
+                    ? cdk.RemovalPolicy.RETAIN
+                    : cdk.RemovalPolicy.DESTROY,
+            }),
+            tracing: lambdaConfig.tracingEnabled
+                ? lambda.Tracing.ACTIVE
+                : lambda.Tracing.DISABLED,
+            reservedConcurrentExecutions: lambdaConfig.reservedConcurrency,
+            role: this.lambdaRole,
+            ...(this.vpc && this.lambdaSecurityGroup
+                ? {
+                    vpc: this.vpc,
+                    vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
+                    securityGroups: [this.lambdaSecurityGroup],
+                }
+                : {}),
+            ...overrides,
+        });
+    }
+    /**
+     * Materialise one queue consumer: a Lambda + an `SqsEventSource`
+     * binding it to the queue ARN imported from the messaging stack.
+     * The DLQ already lives in the messaging tier (RETAIN-class
+     * durability); we don't recreate it here.
+     *
+     * Throws if no matching queue ARN is in `imports.queueArnsById` —
+     * a consumer with no queue is dead infrastructure.
+     */
+    createQueueConsumer(name, handlerFile, intent, imports) {
+        const queueArn = imports.queueArnsById?.get(name);
+        if (!queueArn) {
+            throw new Error(`[venturekit] app stack: queue handler '${name}' (file: ${handlerFile}) ` +
+                `has no matching queue in imports.queueArnsById. The CLI generator ` +
+                `must declare a queues[] intent with id='${name}' so the messaging ` +
+                `stack creates the queue, then pass its ARN through ` +
+                `imports.queueArnsById.set('${name}', queueArn).`);
+        }
+        const resourceId = `queue-consumer-${name}`;
+        const functionName = clampLambdaFunctionName(`${this.projectName}-${this.stage}-queue-${name}`);
+        const fn = this.buildLambda(resourceId, functionName, handlerFile, intent?.description ?? `Queue consumer: ${name}`, {
+            memorySize: intent?.memorySize ?? this.envConfig.lambda.memoryMb,
+            timeout: cdk.Duration.seconds(intent?.timeout ?? this.envConfig.lambda.timeoutSec),
+        });
+        this.queueLambdas.set(name, fn);
+        // `Queue.fromQueueArn` produces an `IQueue` that supports
+        // `addEventSource` via the service principal grant CDK auto-
+        // attaches to the consumer Lambda's role. The role grant
+        // (`sqs:ReceiveMessage`, `DeleteMessage`, `GetQueueAttributes`)
+        // is added to `this.lambdaRole` because the SqsEventSource
+        // constructor calls `queue.grantConsumeMessages(fn)` internally.
+        const importedQueue = sqs.Queue.fromQueueArn(this, `${resourceId}-imported-queue`, queueArn);
+        fn.addEventSource(new lambdaEventSources.SqsEventSource(importedQueue, {
+            batchSize: intent?.batchSize ?? 10,
+        }));
+    }
+    /**
+     * Materialise one scheduled handler: a Lambda + (optional)
+     * EventBridge `Rule` that targets it. When no schedule intent is
+     * declared for the handler, the Lambda is created without a Rule
+     * — the operator can wire the trigger manually post-deploy.
+     *
+     * Each scheduled Lambda gets its own DLQ for async-invoke
+     * failures. Without it, a broken cron silently stops working
+     * after Lambda's 2-retry budget. The DLQ is app-tier (DESTROY-on-
+     * delete): EventBridge-delivery failures don't accumulate
+     * meaningfully across redeploys, and the messaging-tier DLQs are
+     * specific to the notify dispatcher / bounce paths.
+     */
+    createScheduleHandler(name, handlerFile, intent) {
+        const resourceId = `cron-${name}`;
+        const functionName = clampLambdaFunctionName(`${this.projectName}-${this.stage}-cron-${name}`);
+        const dlq = new sqs.Queue(this, `${resourceId}-dlq`, {
+            queueName: `${this.projectName}-${this.stage}-cron-${name}-dlq`,
+            retentionPeriod: cdk.Duration.days(14),
+            encryption: sqs.QueueEncryption.SQS_MANAGED,
+            // App-tier: DESTROY-on-delete. See header comment.
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+        });
+        const fn = this.buildLambda(resourceId, functionName, handlerFile, intent?.description ?? `Cron handler: ${name}`, {
+            memorySize: intent?.memorySize ?? this.envConfig.lambda.memoryMb,
+            // Crons default to 60s timeout (vs 30s for sync routes) —
+            // background jobs are typically heavier than HTTP handlers.
+            timeout: cdk.Duration.seconds(intent?.timeout ?? 60),
+            deadLetterQueue: dlq,
+            deadLetterQueueEnabled: true,
+        });
+        this.scheduleLambdas.set(name, fn);
+        // Optional EventBridge rule. When `intent` is undefined the
+        // handler is created without a trigger — this is intentional
+        // (lets operators stage handler deploys before declaring the
+        // schedule).
+        if (intent?.schedule) {
+            const scheduleExpr = intent.schedule;
+            const isEnabled = intent.enabled ?? true;
+            const schedule = 'rate' in scheduleExpr
+                ? events.Schedule.expression(`rate(${scheduleExpr.rate})`)
+                : events.Schedule.expression(`cron(${scheduleExpr.cron})`);
+            new events.Rule(this, `${resourceId}-rule`, {
+                ruleName: `${this.projectName}-${this.stage}-cron-${name}`,
+                schedule,
+                enabled: isEnabled,
+                targets: [new eventsTargets.LambdaFunction(fn)],
+            });
+        }
+    }
+    /**
+     * Attach IAM grants to the shared Lambda role for every imported
+     * resource. Called once during construction, before any Lambda is
+     * created — CDK collects role policies eagerly at synth, so the
+     * order doesn't matter, but co-locating all grants in one helper
+     * makes the policy surface auditable.
+     *
+     * Grant inventory:
+     *   - DB master credential secret read (one per database)
+     *   - Federated provider Secret reads (one per provider per auth intent)
+     *   - WhatsApp token Secret reads (one per notify intent with channel)
+     *   - S3 bucket read+write (one per storage intent)
+     *   - Cognito admin actions (one per auth intent's user pool)
+     *   - SES send (account-level, scoped via configuration set)
+     *
+     * SQS receive grants come from `SqsEventSource` per consumer
+     * Lambda, NOT here, because they need the role+function pair and
+     * are added at consumer-creation time. Same for HttpApi invoke
+     * (added by `HttpLambdaIntegration`) and EventBridge invoke
+     * (added by `LambdaFunction` target).
+     */
+    applyImportedGrants(imports) {
+        // ── DB secrets ────────────────────────────────────────────
+        if (imports.databaseEndpointsById) {
+            for (const [id, db] of imports.databaseEndpointsById) {
+                if (!db.secretArn)
+                    continue;
+                const importedSecret = secretsmanager.Secret.fromSecretCompleteArn(this, `imported-db-secret-${id}`, db.secretArn);
+                importedSecret.grantRead(this.lambdaRole);
+            }
+        }
+        // ── Federated provider secrets ────────────────────────────
+        if (imports.federatedSecretArnsByAuthId) {
+            for (const [authId, providers] of imports.federatedSecretArnsByAuthId) {
+                for (const [provider, arn] of Object.entries(providers)) {
+                    const importedSecret = secretsmanager.Secret.fromSecretCompleteArn(this, `imported-fed-secret-${authId}-${provider}`, arn);
+                    importedSecret.grantRead(this.lambdaRole);
+                }
+            }
+        }
+        // ── WhatsApp token secrets ────────────────────────────────
+        if (imports.whatsappTokenSecretArnsById) {
+            for (const [id, arn] of imports.whatsappTokenSecretArnsById) {
+                const importedSecret = secretsmanager.Secret.fromSecretCompleteArn(this, `imported-whatsapp-secret-${id}`, arn);
+                importedSecret.grantRead(this.lambdaRole);
+            }
+        }
+        // ── S3 buckets (read+write) ──────────────────────────────
+        if (imports.storageBucketNamesById) {
+            for (const [id, bucketName] of imports.storageBucketNamesById) {
+                const bucket = s3.Bucket.fromBucketName(this, `imported-bucket-${id}`, bucketName);
+                bucket.grantReadWrite(this.lambdaRole);
+            }
+        }
+        // ── Cognito admin actions per user pool ──────────────────
+        if (imports.userPoolArnsByAuthId) {
+            for (const [, poolArn] of imports.userPoolArnsByAuthId) {
+                // Scope to specific Cognito admin actions used by
+                // `@venturekit/auth/server`'s federated sign-in path.
+                // Avoid `cognito-idp:*` — overly broad, includes pool
+                // delete/update which Lambdas should never do.
+                this.lambdaRole.addToPrincipalPolicy(new iam.PolicyStatement({
+                    effect: iam.Effect.ALLOW,
+                    actions: [
+                        'cognito-idp:AdminCreateUser',
+                        'cognito-idp:AdminGetUser',
+                        'cognito-idp:AdminConfirmSignUp',
+                        'cognito-idp:AdminInitiateAuth',
+                        'cognito-idp:AdminSetUserPassword',
+                        'cognito-idp:AdminUpdateUserAttributes',
+                        'cognito-idp:AdminLinkProviderForUser',
+                        'cognito-idp:ListUsers',
+                    ],
+                    resources: [poolArn],
+                }));
+            }
+        }
+        // ── SES send ─────────────────────────────────────────────
+        // SES grants are account-level; the security boundary comes
+        // from `ConfigurationSetName` (validated server-side against
+        // the configured identity). No `Resource: *` workaround
+        // because SES doesn't support resource-level scoping for
+        // SendEmail.
+        if (imports.notifyConfigurationSetNamesById && imports.notifyConfigurationSetNamesById.size > 0) {
+            this.lambdaRole.addToPrincipalPolicy(new iam.PolicyStatement({
+                effect: iam.Effect.ALLOW,
+                actions: ['ses:SendEmail', 'ses:SendRawEmail'],
+                resources: ['*'],
+            }));
+        }
+        // ── SNS publish on notify events topics ─────────────────
+        // Used by the dispatcher to publish synthetic events when an
+        // operator triggers a manual replay. App handlers don't
+        // typically publish here; the grant exists for the dispatcher
+        // alone but lives on the shared role for the same accumulator
+        // reasons documented elsewhere.
+        if (imports.notifyEventsTopicArnsById) {
+            const topicArns = [...imports.notifyEventsTopicArnsById.values()];
+            if (topicArns.length > 0) {
+                this.lambdaRole.addToPrincipalPolicy(new iam.PolicyStatement({
+                    effect: iam.Effect.ALLOW,
+                    actions: ['sns:Publish'],
+                    resources: topicArns,
+                }));
+            }
+        }
+    }
+    /**
+     * Provision dispatcher + bounce-handler Lambdas per declared
+     * `notify[]` intent. The Lambdas bundle stub modules shipped
+     * by `@venturekit/notify` from the consumer's `node_modules`;
+     * the stubs delegate to the operator's notify client module at
+     * runtime. Each Lambda gets its on-failure DLQ from the
+     * messaging tier (RETAIN-class) — losing those DLQs across
+     * redeploys would discard the canonical record of failed
+     * deliveries.
+     *
+     * # Why both Lambdas live HERE not in messaging stack
+     *
+     * The Lambdas are throwaway app-tier code; their schedule
+     * (EventBridge rule) and DLQs (messaging-tier RETAIN) are
+     * separate concerns. Co-locating the handler with the rule + DLQ
+     * would force the messaging stack to depend on the handler
+     * code's bundled hash, which churns every code change and
+     * defeats the lifecycle split.
+     */
+    provisionNotifyHandlers(notifyIntents, projectDir, imports) {
+        if (this.skipBundling) {
+            // In test mode we still want to verify dispatcher / bounce
+            // *resources* exist, but we can't resolve `@venturekit/notify`
+            // in the test sandbox. Use the inline stub path; bundling
+            // helper handles it.
+        }
+        // Resolve stub paths from the consumer's `node_modules`. Skip
+        // resolution entirely when bundling is off (test mode); the
+        // inline stub path doesn't need real handler files.
+        let dispatcherStubSrc = '';
+        let bounceStubSrc = '';
+        if (!this.skipBundling) {
+            const projectRequire = createRequire(path.join(projectDir, 'package.json'));
+            try {
+                dispatcherStubSrc = projectRequire.resolve('@venturekit/notify/runtime/dispatcher-stub');
+                bounceStubSrc = projectRequire.resolve('@venturekit/notify/runtime/bounce-handler-stub');
+            }
+            catch (err) {
+                throw new Error(`[venturekit] notify intent declared but '@venturekit/notify' is not ` +
+                    `installed in the project. Run \`pnpm add @venturekit/notify\` ` +
+                    `(or your equivalent) and redeploy. Underlying error: ${err.message}`);
+            }
+        }
+        // Materialize per-intent stub copies under `.vk/`. Per-intent
+        // copies (named by id) prevent collisions when the operator
+        // declares multiple notify intents with separate client
+        // modules (e.g. transactional vs marketing).
+        const vkDir = path.join(projectDir, '.vk');
+        if (!this.skipBundling) {
+            fs.mkdirSync(vkDir, { recursive: true });
+        }
+        for (const intent of notifyIntents) {
+            const id = String(intent.id);
+            const dispatchRateMinutes = intent.dispatchRateMinutes && intent.dispatchRateMinutes >= 1
+                ? intent.dispatchRateMinutes
+                : 1;
+            const batchSize = intent.dispatchBatchSize && intent.dispatchBatchSize >= 1
+                ? intent.dispatchBatchSize
+                : 50;
+            let dispatchStubPath = `${id}-dispatcher.ts`;
+            let bouncerStubPath = `${id}-bounce.ts`;
+            if (!this.skipBundling) {
+                dispatchStubPath = path.join(vkDir, `notify-${id}-dispatcher.ts`);
+                bouncerStubPath = path.join(vkDir, `notify-${id}-bounce.ts`);
+                fs.copyFileSync(dispatcherStubSrc, dispatchStubPath);
+                fs.copyFileSync(bounceStubSrc, bouncerStubPath);
+            }
+            // ── Dispatcher Lambda + cron rule ────────────────────────
+            const dispatcherFnId = `notify-${id}-dispatcher`;
+            const dispatcherDlqArn = imports.notifyDispatcherDlqArnsById?.get(id);
+            const dispatcherDlq = dispatcherDlqArn
+                ? sqs.Queue.fromQueueArn(this, `${dispatcherFnId}-dlq-imported`, dispatcherDlqArn)
+                : undefined;
+            const dispatcherFn = this.buildLambda(dispatcherFnId, clampLambdaFunctionName(`${this.projectName}-${this.stage}-${dispatcherFnId}`), dispatchStubPath, `Notify dispatcher for '${id}' — drains the outbox.`, {
+                timeout: cdk.Duration.seconds(60),
+                environment: {
+                    ...this.baseEnvVars,
+                    ...this.envConfig.lambda.environmentVariables,
+                    VENTURE_NOTIFY_BATCH_SIZE: String(batchSize),
+                    VENTURE_NOTIFY_INTENT_ID: id,
+                },
+                ...(dispatcherDlq
+                    ? { deadLetterQueue: dispatcherDlq, deadLetterQueueEnabled: true }
+                    : {}),
+            });
+            this.notifyDispatcherLambdas.set(id, dispatcherFn);
+            new events.Rule(this, `${dispatcherFnId}-rule`, {
+                ruleName: `${this.projectName}-${this.stage}-${dispatcherFnId}`,
+                schedule: events.Schedule.rate(cdk.Duration.minutes(dispatchRateMinutes)),
+                enabled: true,
+                targets: [new eventsTargets.LambdaFunction(dispatcherFn)],
+            });
+            // ── Bounce-handler Lambda + SNS subscription ─────────────
+            const bounceFnId = `notify-${id}-bounce-handler`;
+            const bounceDlqArn = imports.notifyBounceDlqArnsById?.get(id);
+            const bounceDlq = bounceDlqArn
+                ? sqs.Queue.fromQueueArn(this, `${bounceFnId}-dlq-imported`, bounceDlqArn)
+                : undefined;
+            const bounceFn = this.buildLambda(bounceFnId, clampLambdaFunctionName(`${this.projectName}-${this.stage}-${bounceFnId}`), bouncerStubPath, `Notify bounce/complaint handler for '${id}'.`, {
+                timeout: cdk.Duration.seconds(30),
+                environment: {
+                    ...this.baseEnvVars,
+                    ...this.envConfig.lambda.environmentVariables,
+                    VENTURE_NOTIFY_INTENT_ID: id,
+                },
+                ...(bounceDlq
+                    ? { deadLetterQueue: bounceDlq, deadLetterQueueEnabled: true }
+                    : {}),
+            });
+            this.notifyBounceLambdas.set(id, bounceFn);
+            // Subscribe to the events topic. Topic lives in messaging
+            // stack — import via ARN. CDK's `LambdaSubscription` adds
+            // the `lambda:InvokeFunction` resource policy on the bounce
+            // Lambda granting SNS the right to invoke it.
+            const topicArn = imports.notifyEventsTopicArnsById?.get(id);
+            if (topicArn) {
+                const importedTopic = sns.Topic.fromTopicArn(this, `${bounceFnId}-topic-imported`, topicArn);
+                importedTopic.addSubscription(new snsSubscriptions.LambdaSubscription(bounceFn));
+            }
+        }
+    }
+}
+//# sourceMappingURL=app-stack.js.map