@venturekit/infra 0.0.0-dev.20260514025106 → 0.0.0-dev.20260515021849

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

@@ -0,0 +1,330 @@
+/**
+ * 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 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 apigatewayv2 from 'aws-cdk-lib/aws-apigatewayv2';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import { Construct } from 'constructs';
+import { type EnvConfig, type VentureIntent } from '@venturekit/core';
+/**
+ * Imported cross-stack refs the CLI generator passes in. Every field
+ * is optional because not every project declares every tier — a free-
+ * tier project with no auth + no notify + no VPC needs none of these.
+ */
+export interface AppStackImports {
+    /**
+     * Imported VPC, when the lower-tier stacks created one. Resolved
+     * from `networkKeys.vpcId` SSM or constructed via
+     * `Vpc.fromVpcAttributes` by the generator. App stack uses it to
+     * re-attach the shared Lambda SG and to issue VPC-bound Lambda
+     * functions.
+     */
+    vpc?: ec2.IVpc;
+    /**
+     * HttpApi imported from the edge stack via
+     * `HttpApi.fromHttpApiAttributes({ httpApiId, apiEndpoint })`.
+     * The app stack registers routes on this API.
+     */
+    api?: apigatewayv2.IHttpApi;
+    /**
+     * Cognito User Pool ARN per declared `auth` intent — for
+     * `cognito-idp:Admin*` grant scoping. Resolved by the generator
+     * from `identityKeys.userPoolArn` SSM.
+     */
+    userPoolArnsByAuthId?: Map<string, string>;
+    /** Federated-provider Secret ARNs per auth intent. */
+    federatedSecretArnsByAuthId?: Map<string, Record<string, string>>;
+    /** S3 bucket names per `storage` intent — for env-var injection + grant. */
+    storageBucketNamesById?: Map<string, string>;
+    /** SQS queue ARNs per `queues` intent — for grant + ESM source. */
+    queueArnsById?: Map<string, string>;
+    /** SNS notify events topic ARNs per `notify` intent. */
+    notifyEventsTopicArnsById?: Map<string, string>;
+    /** CloudFront CDN domain per storage intent that has `cdn:true`. */
+    storageCdnDomainsById?: Map<string, string>;
+    /** SES configuration set names per `notify` intent. */
+    notifyConfigurationSetNamesById?: Map<string, string>;
+    /** WhatsApp token Secret ARNs per `notify` intent (when channel enabled). */
+    whatsappTokenSecretArnsById?: Map<string, string>;
+    /**
+     * Dispatcher on-failure DLQ ARN per `notify` intent. Created
+     * by the messaging stack (RETAIN-class). The dispatcher Lambda
+     * uses this as its async-invoke `deadLetterQueue` so a broken
+     * dispatcher's failures accumulate across redeploys.
+     */
+    notifyDispatcherDlqArnsById?: Map<string, string>;
+    /** Same idea for the bounce-handler Lambda. */
+    notifyBounceDlqArnsById?: Map<string, string>;
+    /**
+     * DB connection params per `database` intent. The generator
+     * resolves these from `dataKeys.rdsEndpoint*` SSM lookups so
+     * env-var injection happens at app-stack synth, not Lambda
+     * runtime.
+     */
+    databaseEndpointsById?: Map<string, {
+        host: string;
+        port: string;
+        name: string;
+        secretArn?: string;
+    }>;
+}
+export interface VentureAppStackProps extends cdk.StackProps {
+    projectName: string;
+    stage: string;
+    envConfig: EnvConfig;
+    /** Full intent surface — Lambda discovery walks `routes`, `queues`, etc. */
+    infrastructure: VentureIntent;
+    /** Cross-stack imports (network/data/identity/config/messaging/edge). */
+    imports: AppStackImports;
+    /**
+     * Project root directory — the dir containing `package.json` +
+     * `node_modules`. Used as the bundling asset root so esbuild
+     * resolves handler imports against installed dependencies.
+     * Required when any Lambda intent is declared; ignored otherwise.
+     */
+    projectDir?: string;
+    /**
+     * Routes directory relative to `projectDir`. Defaults to `src/routes`
+     * matching the local-dev server convention. Walked by
+     * `discoverRouteFiles` to produce one Lambda per file. Pass an
+     * empty string or non-existent path to skip route discovery
+     * entirely.
+     */
+    routesDir?: string;
+    /**
+     * Queue handlers directory. Defaults to `src/queues`. Each file
+     * becomes one consumer Lambda; the corresponding queue (by id ===
+     * file-derived name) MUST be present in `imports.queueArnsById`,
+     * otherwise the consumer has nothing to consume and we throw at
+     * synth time.
+     */
+    queuesDir?: string;
+    /**
+     * Cron handlers directory. Defaults to `src/crons`. Each file
+     * becomes one Lambda; the corresponding `schedules[]` intent (by
+     * id) provides the schedule expression. Files without a matching
+     * intent are created as Lambdas WITHOUT an EventBridge rule —
+     * the operator can wire the schedule manually post-deploy.
+     */
+    cronsDir?: string;
+    /**
+     * @internal Test-only flag: when true, every Lambda uses an inline
+     * stub instead of Docker bundling. Cuts test runtimes from minutes
+     * to seconds and avoids requiring Docker on CI.
+     */
+    skipBundling?: boolean;
+}
+/**
+ * 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 declare class VentureAppStack extends cdk.Stack {
+    /** Shared execution role for every Lambda in this stack. */
+    readonly lambdaRole: iam.Role;
+    /** Shared SG when a VPC is imported; undefined for VPC-less projects. */
+    readonly lambdaSecurityGroup?: ec2.SecurityGroup;
+    /** Internal HMAC signing secret for Lambda-to-Lambda `invoke()`. */
+    readonly internalHmacSecret: secretsmanager.Secret;
+    /**
+     * 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.
+     */
+    readonly baseEnvVars: Record<string, string>;
+    /** The imported HttpApi — sub-step 9b registers routes on this. */
+    readonly api?: apigatewayv2.IHttpApi;
+    /** Imported VPC, when present. */
+    readonly vpc?: ec2.IVpc;
+    /**
+     * 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.
+     */
+    readonly routeLambdas: Map<string, lambda.Function>;
+    /** Queue consumer Lambdas keyed by handler name. */
+    readonly queueLambdas: Map<string, lambda.Function>;
+    /** Scheduled / cron Lambdas keyed by handler name. */
+    readonly scheduleLambdas: Map<string, lambda.Function>;
+    /** Notify dispatcher Lambdas keyed by notify intent id. */
+    readonly notifyDispatcherLambdas: Map<string, lambda.Function>;
+    /** Notify bounce-handler Lambdas keyed by notify intent id. */
+    readonly notifyBounceLambdas: Map<string, lambda.Function>;
+    private readonly isStrictRetain;
+    private readonly projectName;
+    private readonly stage;
+    private readonly envConfig;
+    private readonly skipBundling;
+    private readonly projectDir;
+    constructor(scope: Construct, id: string, props: VentureAppStackProps);
+    /**
+     * 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.
+     */
+    private bundleHandlerCode;
+    /**
+     * 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.
+     */
+    private createRouteFunction;
+    /**
+     * 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.
+     */
+    private buildLambda;
+    /**
+     * 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.
+     */
+    private createQueueConsumer;
+    /**
+     * 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.
+     */
+    private createScheduleHandler;
+    /**
+     * 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).
+     */
+    private applyImportedGrants;
+    /**
+     * 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.
+     */
+    private provisionNotifyHandlers;
+}
+//# sourceMappingURL=app-stack.d.ts.map

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

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