@aws-blocks/core 0.4.0 → 0.5.0

package/dist/cdk/vpc-types.d.ts

@@ -0,0 +1,151 @@
+import type * as ec2 from 'aws-cdk-lib/aws-ec2';
+/**
+ * A subnet role — the kind of subnet a Building Block needs, expressed as an
+ * intent the VPC resolves to a concrete {@link ec2.SubnetSelection}:
+ *
+ * - `'private-with-egress'` — private subnets with outbound internet access via
+ *   a NAT gateway. Required by anything that must reach a public AWS endpoint at
+ *   runtime (e.g. a service with no interface endpoint).
+ * - `'isolated'` — private subnets with no internet route at all. Best for
+ *   resources reached entirely over VPC endpoints or in-VPC (e.g. a database).
+ * - `'public'` — subnets with a direct internet gateway route.
+ */
+export type SubnetRole = 'private-with-egress' | 'isolated' | 'public';
+/**
+ * Options for VPC integration on BlocksStack / BlocksBackend.
+ *
+ * @example
+ * ```ts
+ * const vpc = new ec2.Vpc(app, 'AppVpc', { maxAzs: 2, natGateways: 1 });
+ * await BlocksStack.create(app, stackName, {
+ *   backendHandlerPath: join(__dirname, 'index.handler.ts'),
+ *   backendCDKPath: join(__dirname, 'index.ts'),
+ *   defaults: { ...BlocksPresets.production, vpc: { network: vpc } },
+ * });
+ * ```
+ */
+export interface BlocksVpcOptions {
+    /**
+     * The VPC to place Lambdas and VPC-resident resources into.
+     * Create this however you like — standard CDK:
+     *
+     * @example
+     * const vpc = new ec2.Vpc(stack, 'AppVpc', { maxAzs: 2, natGateways: 1 });
+     * // or
+     * const vpc = ec2.Vpc.fromLookup(stack, 'SharedVpc', { vpcId: 'vpc-abc123' });
+     */
+    network: ec2.IVpc;
+    /**
+     * Subnet selection for Lambda and Blocks-managed compute placement.
+     *
+     * Any subnets you select must belong to {@link network}. This is not
+     * validated at synth — CDK can't check it for an imported subnet (which
+     * carries no `vpcId`) — so a mismatch surfaces as a CloudFormation error at
+     * deploy, not a synth-time failure.
+     *
+     * @default { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }
+     */
+    subnets?: ec2.SubnetSelection;
+    /**
+     * Whether to auto-provision VPC endpoints based on BB registrations.
+     * Set to `false` to disable (e.g., when using a shared VPC that already has endpoints).
+     *
+     * @default true
+     */
+    provisionEndpoints?: boolean;
+}
+/**
+ * VPC requirements declared by a Building Block.
+ * Supplied to the `BuildingBlockScope` constructor and collected in the central
+ * requirements registry; `finalizeVpc` pulls them to provision endpoints, and the
+ * lazy VPC uses `requiresVpc` to decide whether to derive a VPC when none was
+ * provided.
+ */
+export interface VpcRequirements {
+    /** Gateway VPC endpoints this BB needs (e.g., S3, DynamoDB). */
+    gatewayEndpoints?: ec2.GatewayVpcEndpointAwsService[];
+    /** Interface VPC endpoints this BB needs (e.g., SQS, SSM, Secrets Manager). */
+    interfaceEndpoints?: ec2.InterfaceVpcEndpointAwsService[];
+    /**
+     * Whether this BB **cannot function without a VPC** — i.e. it must run in (or
+     * provision resources into) a VPC regardless of whether the customer asked
+     * for one. When any registered requirement sets this and no `vpc` was
+     * provided, the framework **lazily derives** a default VPC (see
+     * `getOrCreateVpc`) rather than erroring — mirroring how bb-data creates its
+     * own VPC when no shared one exists.
+     *
+     * Most BBs leave this unset: they reach AWS services from the AWS-managed
+     * Lambda network and only *benefit* from a VPC (endpoints) when one is present.
+     * Set it only for a BB whose resources are intrinsically VPC-resident.
+     *
+     * @default false
+     */
+    requiresVpc?: boolean;
+    /**
+     * Whether the BB's **parent runtime** — the shared Blocks handler Lambda (or,
+     * in future, a container) that executes this BB's operations — must be able to
+     * reach the internet (outbound egress) for the BB to work at runtime.
+     *
+     * Set this when your BB's runtime code calls a service it can only reach over
+     * the public internet. The canonical case: a service with no VPC endpoint
+     * (e.g. Aurora DSQL) is reached over a public HTTPS endpoint, so the runtime
+     * must sit in a subnet with an egress route; if it's placed in isolated
+     * subnets the deploy still succeeds but every call times out at runtime.
+     *
+     * The framework **validates** this at synth against the runtime's resolved
+     * placement (egress is satisfied by a `private-with-egress` or `public`
+     * selection) and fails the build with an actionable message on a mismatch. It
+     * never moves the runtime — reassigning a customer's explicit placement is not
+     * a BB's responsibility, so an unsatisfiable requirement is an error, not a
+     * silent relocation.
+     *
+     * This constrains the BB's **host**. To place compute the BB provisions
+     * **itself** (e.g. an Aurora cluster), resolve a subnet inline in your
+     * constructor via {@link VpcContext.selectSubnets} instead.
+     *
+     * @default false
+     */
+    requiresEgress?: boolean;
+}
+/**
+ * The minimal shape {@link VpcContext.selectSubnets} needs from a Building
+ * Block to produce an instructive, BB-named error — just its `fullId`. Typed
+ * structurally so `vpc-types.ts` stays type-only and free of a dependency on
+ * the `Scope` class.
+ */
+export interface SubnetScope {
+    readonly fullId: string;
+}
+/**
+ * Internal VPC context propagated through the construct tree.
+ * Set by the CDK-level VPC option. BBs read this to determine their VPC placement.
+ * @internal
+ */
+export interface VpcContext {
+    readonly vpc: ec2.IVpc;
+    readonly computeSecurityGroup: ec2.ISecurityGroup;
+    readonly computeSubnets: ec2.SubnetSelection;
+    /**
+     * Resolve a {@link SubnetRole} to a concrete {@link ec2.SubnetSelection} for a
+     * resource this Building Block provisions itself, verifying the VPC actually
+     * has subnets of that role.
+     *
+     * Prefer this over building an `ec2.SubnetSelection` by hand: if the VPC has
+     * no matching subnet, it throws an actionable, BB-named error at synth
+     * ("`KVStore 'app/cache'` needs an 'isolated' subnet, but VPC 'vpc-…' has
+     * none …") instead of the opaque CDK "no subnet groups" error thrown later.
+     *
+     * @param scope   the BB requesting the subnet (its `fullId` names the error)
+     * @param role    the subnet role the BB's own resource needs
+     * @param opts.fallback  an alternate role to use when `role` is absent from
+     *   the VPC. Provide it to **explicitly** allow graceful degradation (e.g.
+     *   Aurora over the Data API works from `'private-with-egress'` when there is
+     *   no isolated tier); omit it to require `role` strictly and fail otherwise.
+     *   The downgrade is never silent — it only happens when you opt in here.
+     * @throws if the VPC has neither `role` nor (when given) `opts.fallback`
+     */
+    selectSubnets(scope: SubnetScope, role: SubnetRole, opts?: {
+        fallback?: SubnetRole;
+    }): ec2.SubnetSelection;
+}
+//# sourceMappingURL=vpc-types.d.ts.map

package/dist/cdk/vpc-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-types.d.ts","sourceRoot":"","sources":["../../src/cdk/vpc-types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,qBAAqB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;OAQG;IACH,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC;IAElB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,eAAe,CAAC;IAE9B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,GAAG,CAAC,4BAA4B,EAAE,CAAC;IACtD,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,GAAG,CAAC,8BAA8B,EAAE,CAAC;IAC1D;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC;IACvB,QAAQ,CAAC,oBAAoB,EAAE,GAAG,CAAC,cAAc,CAAC;IAClD,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,eAAe,CAAC;IAC7C;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,GAAG,CAAC,eAAe,CAAC;CAC3G"}

package/dist/cdk/vpc-types.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/cdk/vpc.d.ts

@@ -0,0 +1,59 @@
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import type { Construct } from 'constructs';
+import type { BlocksVpcOptions, VpcContext } from './vpc-types.js';
+/**
+ * Set the VPC context on a scope (BlocksStack or BlocksBackend).
+ * Called during stack creation when `vpc` prop is provided.
+ * @internal
+ */
+export declare function setVpcContext(scope: Construct, context: VpcContext): void;
+/**
+ * Get the VPC context from a scope by walking up the construct tree.
+ * Used by BBs (e.g., bb-data) to discover the shared VPC.
+ * @internal
+ */
+export declare function getVpcContext(scope: Construct): VpcContext | undefined;
+/**
+ * Does any registered Building Block *require* a VPC (i.e. cannot function
+ * without one)? Used to decide whether to lazily derive a VPC when the customer
+ * didn't provide one. A BB that merely benefits from endpoints does NOT count —
+ * only `requiresVpc: true`.
+ * @internal
+ */
+export declare function anyRequirementNeedsVpc(scope: Construct): boolean;
+/**
+ * Get the framework-owned VPC for a stack, creating one on first use.
+ *
+ * VPC is a **derived** resource: when a Building Block (or, later, a container
+ * compute) requires one and the customer didn't bring their own, Blocks
+ * materializes a sensible default here — the same create-if-absent pattern
+ * `bb-data` uses for Aurora, lifted to the framework so the whole app shares a
+ * single VPC. Keyed by a Symbol on the stack so it's a true singleton: the first
+ * caller creates, everyone else reuses. Passing a customer VPC (`vpc:` prop)
+ * pre-seeds this via {@link initializeVpc}, so this default is only built when
+ * nothing was provided.
+ *
+ * The default has both a `private-with-egress` tier (for a runtime that needs
+ * outbound access — the derivation trigger) and public subnets for the NAT
+ * gateway. NAT has a real cost, so this is only created on genuine need, and
+ * `create()` emits a notice when it does.
+ * @internal
+ */
+export declare function getOrCreateVpc(scope: Construct): ec2.IVpc;
+/**
+ * Initialize VPC support on a Blocks scope (BlocksStack or BlocksBackend).
+ * Creates the security group, sets VPC context, and returns the VpcContext
+ * that is used for Lambda placement configuration.
+ *
+ * Called during setupBlocksInfra when `vpc` prop is present.
+ * @internal
+ */
+export declare function initializeVpc(scope: Construct, options: BlocksVpcOptions): VpcContext;
+/**
+ * Finalize VPC: query all BuildingBlockScope children for their VPC requirements,
+ * deduplicate, and provision endpoints.
+ * Called after all BBs are constructed (alongside finalizeConfigRegistry).
+ * @internal
+ */
+export declare function finalizeVpc(scope: Construct, options: BlocksVpcOptions): void;
+//# sourceMappingURL=vpc.d.ts.map

package/dist/cdk/vpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc.d.ts","sourceRoot":"","sources":["../../src/cdk/vpc.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAA2B,UAAU,EAAmB,MAAM,gBAAgB,CAAC;AA4B7G;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAQtE;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,IAAI,CAOzD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAkDrF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAyH7E"}

package/dist/cdk/vpc.js

@@ -0,0 +1,298 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Annotations } from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { getVpcRequirements as getRegisteredVpcRequirements } from './vpc-requirements-registry.js';
+const VPC_CONTEXT_KEY = Symbol.for('BLOCKS_VPC_CONTEXT');
+/** Map a subnet role to its concrete CDK subnet type. */
+function subnetTypeForRole(role) {
+    switch (role) {
+        case 'isolated':
+            return ec2.SubnetType.PRIVATE_ISOLATED;
+        case 'public':
+            return ec2.SubnetType.PUBLIC;
+        case 'private-with-egress':
+            return ec2.SubnetType.PRIVATE_WITH_EGRESS;
+    }
+}
+/** Does the VPC actually contain at least one subnet of the given role? */
+function vpcHasRole(vpc, role) {
+    switch (role) {
+        case 'isolated':
+            return vpc.isolatedSubnets.length > 0;
+        case 'public':
+            return vpc.publicSubnets.length > 0;
+        case 'private-with-egress':
+            return vpc.privateSubnets.length > 0;
+    }
+}
+/**
+ * Set the VPC context on a scope (BlocksStack or BlocksBackend).
+ * Called during stack creation when `vpc` prop is provided.
+ * @internal
+ */
+export function setVpcContext(scope, context) {
+    scope[VPC_CONTEXT_KEY] = context;
+}
+/**
+ * Get the VPC context from a scope by walking up the construct tree.
+ * Used by BBs (e.g., bb-data) to discover the shared VPC.
+ * @internal
+ */
+export function getVpcContext(scope) {
+    let current = scope;
+    while (current) {
+        const ctx = current[VPC_CONTEXT_KEY];
+        if (ctx)
+            return ctx;
+        current = current.node.scope;
+    }
+    return undefined;
+}
+const LAZY_VPC_KEY = Symbol.for('BLOCKS_LAZY_VPC');
+/**
+ * Does any registered Building Block *require* a VPC (i.e. cannot function
+ * without one)? Used to decide whether to lazily derive a VPC when the customer
+ * didn't provide one. A BB that merely benefits from endpoints does NOT count —
+ * only `requiresVpc: true`.
+ * @internal
+ */
+export function anyRequirementNeedsVpc(scope) {
+    return getRegisteredVpcRequirements(scope).some((r) => r.requirements.requiresVpc === true);
+}
+/**
+ * Get the framework-owned VPC for a stack, creating one on first use.
+ *
+ * VPC is a **derived** resource: when a Building Block (or, later, a container
+ * compute) requires one and the customer didn't bring their own, Blocks
+ * materializes a sensible default here — the same create-if-absent pattern
+ * `bb-data` uses for Aurora, lifted to the framework so the whole app shares a
+ * single VPC. Keyed by a Symbol on the stack so it's a true singleton: the first
+ * caller creates, everyone else reuses. Passing a customer VPC (`vpc:` prop)
+ * pre-seeds this via {@link initializeVpc}, so this default is only built when
+ * nothing was provided.
+ *
+ * The default has both a `private-with-egress` tier (for a runtime that needs
+ * outbound access — the derivation trigger) and public subnets for the NAT
+ * gateway. NAT has a real cost, so this is only created on genuine need, and
+ * `create()` emits a notice when it does.
+ * @internal
+ */
+export function getOrCreateVpc(scope) {
+    const holder = scope;
+    const existing = holder[LAZY_VPC_KEY];
+    if (existing)
+        return existing;
+    const vpc = new ec2.Vpc(scope, 'BlocksVpc', { maxAzs: 2, natGateways: 1 });
+    holder[LAZY_VPC_KEY] = vpc;
+    return vpc;
+}
+/**
+ * Initialize VPC support on a Blocks scope (BlocksStack or BlocksBackend).
+ * Creates the security group, sets VPC context, and returns the VpcContext
+ * that is used for Lambda placement configuration.
+ *
+ * Called during setupBlocksInfra when `vpc` prop is present.
+ * @internal
+ */
+export function initializeVpc(scope, options) {
+    const { network: vpc, subnets } = options;
+    // Default Lambda placement to private-with-egress. Guard the default: if the
+    // caller didn't specify `subnets` and the VPC has no such tier, fail now with
+    // an actionable message instead of letting Lambda placement throw a cryptic
+    // CDK error later. (A caller who *explicitly* passes an isolated selection is
+    // honored — per-BB `requiresEgress` validation catches BBs that can't run there.)
+    if (!subnets && !vpcHasRole(vpc, 'private-with-egress')) {
+        throw new Error(`VPC '${vpc.vpcId}' has no private-with-egress subnets, which Blocks uses for Lambda ` +
+            `placement by default. Add a PRIVATE_WITH_EGRESS subnet tier (a private subnet with a ` +
+            `NAT gateway), or pass 'vpc.subnets' to choose a different placement explicitly. ` +
+            `See packages/blocks/VPC.md.`);
+    }
+    const resolvedSubnets = subnets ?? { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS };
+    const computeSecurityGroup = new ec2.SecurityGroup(scope, 'BlocksLambdaSg', {
+        vpc,
+        description: 'Security group for Blocks Lambda functions in VPC',
+        allowAllOutbound: true,
+    });
+    const context = {
+        vpc,
+        computeSecurityGroup,
+        computeSubnets: resolvedSubnets,
+        selectSubnets(scope, role, opts) {
+            if (vpcHasRole(vpc, role)) {
+                return { subnetType: subnetTypeForRole(role) };
+            }
+            // Requested role is absent. Fall back only if the BB explicitly opted in
+            // AND the fallback role actually exists — never downgrade silently.
+            if (opts?.fallback && vpcHasRole(vpc, opts.fallback)) {
+                return { subnetType: subnetTypeForRole(opts.fallback) };
+            }
+            const wanted = opts?.fallback ? `'${role}' (or '${opts.fallback}')` : `'${role}'`;
+            throw new Error(`${scope.fullId} needs a ${wanted} subnet, but VPC '${vpc.vpcId}' has none. ` +
+                `Add a matching subnet tier to your VPC (e.g. a 'subnetConfiguration' entry of the ` +
+                `required type), or place the Building Block differently. ` +
+                `See packages/blocks/VPC.md for guidance.`);
+        },
+    };
+    setVpcContext(scope, context);
+    return context;
+}
+/**
+ * Finalize VPC: query all BuildingBlockScope children for their VPC requirements,
+ * deduplicate, and provision endpoints.
+ * Called after all BBs are constructed (alongside finalizeConfigRegistry).
+ * @internal
+ */
+export function finalizeVpc(scope, options) {
+    const { network: vpc, subnets } = options;
+    // Whether the runtime's placement provides egress (outbound internet). This is
+    // the only capability the requirement check needs — a BB either needs egress
+    // or it doesn't. Resolved from the actual selected subnets rather than guessed
+    // from a subnet role, so an explicit subnet *list* (no subnetType) is handled
+    // correctly. `undefined` = couldn't determine (e.g. an imported VPC whose
+    // subnets aren't known at synth) → we skip validation with a warning rather
+    // than fabricate an answer.
+    const placementHasEgress = placementProvidesEgress(vpc, subnets);
+    const gatewayEndpoints = [];
+    const interfaceEndpoints = [];
+    // Pull requirements from the central registry — every BuildingBlockScope
+    // self-registers in its constructor, so this is a faithful census without a
+    // separate tree walk (mirrors how config/compute registries are consumed).
+    for (const { fullId, requirements: reqs } of getRegisteredVpcRequirements(scope)) {
+        if (reqs.gatewayEndpoints) {
+            gatewayEndpoints.push(...reqs.gatewayEndpoints);
+        }
+        if (reqs.interfaceEndpoints) {
+            interfaceEndpoints.push(...reqs.interfaceEndpoints);
+        }
+        // Validate the BB's runtime egress need against where the runtime is
+        // actually placed. We never move the runtime (that's the customer's
+        // explicit choice) — an unsatisfiable requirement is a synth error, not a
+        // silent relocation. This turns an otherwise-silent runtime failure (e.g.
+        // DSQL in an isolated Lambda: deploys clean, times out on every call) into
+        // an actionable build error.
+        if (reqs.requiresEgress) {
+            if (placementHasEgress === false) {
+                throw new Error(`${fullId} requires its runtime to reach the internet (outbound egress), but the ` +
+                    `Blocks runtime is placed in subnets with no egress route. ` +
+                    `Set 'vpc.subnets' to a 'private-with-egress' (or 'public') selection, or remove ` +
+                    `the Building Block that needs it. See packages/blocks/VPC.md.`);
+            }
+            if (placementHasEgress === undefined) {
+                // Couldn't determine egress (e.g. imported VPC with unknown subnets).
+                // Don't fabricate a pass/fail — warn so a real mismatch isn't silent.
+                Annotations.of(scope).addWarningV2('blocks:vpc:egress-unverified', `${fullId} requires runtime egress, but Blocks couldn't determine whether the ` +
+                    `configured subnets provide it (e.g. an imported VPC). Ensure the runtime's subnets ` +
+                    `have an outbound internet route. See packages/blocks/VPC.md.`);
+            }
+        }
+    }
+    if (options.provisionEndpoints === false) {
+        return;
+    }
+    // Always add the S3 gateway endpoint. The runtime pulls config/secrets and
+    // migrations from S3 at cold start, so an in-VPC runtime needs it. Gateway
+    // endpoints are free (route-table entries, no ENI), so this is unconditional.
+    gatewayEndpoints.push(ec2.GatewayVpcEndpointAwsService.S3);
+    // Provision gateway endpoints (deduplicated). Gateway endpoints attach to
+    // route tables, not ENIs, so they have no security-group layer.
+    const provisionedGateway = new Set();
+    for (const service of gatewayEndpoints) {
+        const key = service.name;
+        if (provisionedGateway.has(key))
+            continue;
+        provisionedGateway.add(key);
+        const constructId = `VpcGw${key.replace(/[^a-zA-Z0-9]/g, '')}`;
+        new ec2.GatewayVpcEndpoint(scope, constructId, { vpc, service });
+    }
+    // Always add CloudWatch Logs — every in-VPC Lambda needs it for log delivery,
+    // regardless of which Building Blocks are present. SSM is NOT added here: it
+    // flows from BB requirements (AppSetting and the auth blocks, which compose
+    // AppSetting, declare it), so an app that uses neither doesn't pay for an
+    // unused interface endpoint.
+    interfaceEndpoints.push(ec2.InterfaceVpcEndpointAwsService.CLOUDWATCH_LOGS);
+    // Dedicated security group for the interface endpoints. Without an explicit
+    // SG, CDK creates a default that allows 443 from the entire VPC CIDR — on a
+    // bring-your-own VPC that exposes every endpoint to unrelated workloads. Scope
+    // ingress to just the Blocks Lambda SG so only our functions can reach them.
+    const ctx = getVpcContext(scope);
+    const endpointSecurityGroup = new ec2.SecurityGroup(scope, 'BlocksVpcEndpointSg', {
+        vpc,
+        description: 'Blocks interface VPC endpoints — 443 from the Blocks Lambda only',
+        allowAllOutbound: true,
+    });
+    if (ctx) {
+        endpointSecurityGroup.addIngressRule(ec2.Peer.securityGroupId(ctx.computeSecurityGroup.securityGroupId), ec2.Port.tcp(443), 'HTTPS from Blocks Lambda');
+    }
+    // Provision interface endpoints (deduplicated)
+    const provisionedInterface = new Set();
+    for (const service of interfaceEndpoints) {
+        const key = service.name;
+        if (provisionedInterface.has(key))
+            continue;
+        provisionedInterface.add(key);
+        const constructId = `VpcIf${key.replace(/[^a-zA-Z0-9]/g, '')}`;
+        new ec2.InterfaceVpcEndpoint(scope, constructId, {
+            vpc,
+            service,
+            privateDnsEnabled: true,
+            securityGroups: [endpointSecurityGroup],
+            // `open: false` suppresses CDK's default "allow 443 from the whole VPC
+            // CIDR" ingress rule. Our dedicated SG already allows 443 from just the
+            // Blocks Lambda SG; without this, CDK would re-widen access to the entire
+            // VPC — the exact broadening this dedicated SG exists to prevent.
+            open: false,
+        });
+    }
+}
+/**
+ * Does the runtime's subnet placement provide egress (an outbound internet
+ * route)? Returns `true`/`false` when determinable, or `undefined` when it
+ * can't be determined at synth (e.g. an imported VPC whose subnets aren't
+ * known) — callers should warn rather than assume.
+ *
+ * Resolved from the actual subnets, not from a subnet *role*, so an explicit
+ * subnet **list** (which carries no `subnetType`) is handled correctly. For a
+ * multi-subnet selection, egress is only reported when **every** selected
+ * subnet has it (a runtime may land in any of them).
+ */
+function placementProvidesEgress(vpc, selection) {
+    // Default placement (no selection) is PRIVATE_WITH_EGRESS — see initializeVpc.
+    if (!selection) {
+        return vpc.privateSubnets.length > 0 ? true : undefined;
+    }
+    // Explicit type: egress iff it's the egress tier; isolated/public are known.
+    if (selection.subnetType !== undefined) {
+        switch (selection.subnetType) {
+            case ec2.SubnetType.PRIVATE_WITH_EGRESS:
+                return true;
+            case ec2.SubnetType.PUBLIC:
+                return true; // public subnets route to an internet gateway
+            case ec2.SubnetType.PRIVATE_ISOLATED:
+                return false;
+            default:
+                return undefined;
+        }
+    }
+    // Explicit subnet list (or filter): resolve the concrete subnets and check
+    // that all of them are egress-capable. If resolution yields nothing usable,
+    // we can't tell.
+    try {
+        const { subnets: selected } = vpc.selectSubnets(selection);
+        if (selected.length === 0)
+            return undefined;
+        // A subnet is egress-capable if it's one of the VPC's private (with-egress)
+        // or public subnets. Isolated subnets are in neither list.
+        const egressCapable = new Set([
+            ...vpc.privateSubnets.map((s) => s.subnetId),
+            ...vpc.publicSubnets.map((s) => s.subnetId),
+        ]);
+        // If the VPC exposes no subnet inventory (imported VPC), we can't classify.
+        if (egressCapable.size === 0 && vpc.isolatedSubnets.length === 0)
+            return undefined;
+        return selected.every((s) => egressCapable.has(s.subnetId));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cdk/vpc.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vpc.test.d.ts.map

package/dist/cdk/vpc.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc.test.d.ts","sourceRoot":"","sources":["../../src/cdk/vpc.test.ts"],"names":[],"mappings":""}