@aws-blocks/core 0.3.0 → 0.5.0

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":""}

package/dist/cdk/vpc.test.js

@@ -0,0 +1,285 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { Construct } from 'constructs';
+import { anyRequirementNeedsVpc, finalizeVpc, getOrCreateVpc, getVpcContext, initializeVpc, setVpcContext, } from './vpc.js';
+import { registerVpcRequirements } from './vpc-requirements-registry.js';
+// A minimal stand-in for a BuildingBlockScope: finalizeVpc reads requirements
+// from the central registry, and the real BuildingBlockScope base registers in
+// its constructor. This fake does the same (register on construction) so it
+// exercises the real pull-and-provision path without pulling every BB package
+// into core's test graph. A `fullId` getter mirrors the real Scope so error
+// messages that name the BB can be asserted.
+class FakeBB extends Construct {
+    constructor(scope, id, reqs) {
+        super(scope, id);
+        registerVpcRequirements(this, reqs);
+    }
+    get fullId() {
+        return this.node.id;
+    }
+}
+/**
+ * Build a stack + VPC, optionally initialize the VPC context (so the endpoint
+ * SG can scope to the Lambda SG), add fake BBs, then run finalizeVpc.
+ */
+function synthWith(bbs, opts) {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'TestStack', { env: { account: '123456789012', region: 'us-east-1' } });
+    const vpc = new ec2.Vpc(stack, 'Vpc', { maxAzs: 2, natGateways: opts?.natGateways ?? 1 });
+    const options = {
+        network: vpc,
+        subnets: opts?.subnets,
+        provisionEndpoints: opts?.provisionEndpoints,
+    };
+    if (opts?.withContext !== false)
+        initializeVpc(stack, options);
+    bbs(stack);
+    finalizeVpc(stack, options);
+    return Template.fromStack(stack);
+}
+const IFACE = 'AWS::EC2::VPCEndpoint';
+/** Count interface vs gateway endpoints in a synthesized template. */
+function endpointCounts(template) {
+    const eps = template.findResources(IFACE);
+    let iface = 0;
+    let gateway = 0;
+    for (const ep of Object.values(eps)) {
+        const type = ep.Properties?.VpcEndpointType;
+        // Interface endpoints set VpcEndpointType: 'Interface'; gateway endpoints
+        // default the property (Gateway) and omit it in the synthesized template.
+        if (type === 'Interface')
+            iface += 1;
+        else
+            gateway += 1;
+    }
+    return { iface, gateway };
+}
+describe('finalizeVpc — endpoint provisioning', () => {
+    it('always provisions CloudWatch Logs (interface) and S3 (gateway), even with no BBs', () => {
+        const template = synthWith(() => { });
+        const { iface, gateway } = endpointCounts(template);
+        assert.equal(gateway, 1); // S3 gateway, always-on (free)
+        assert.equal(iface, 1); // Logs, always-on
+        template.hasResourceProperties(IFACE, {
+            VpcEndpointType: 'Interface',
+            ServiceName: 'com.amazonaws.us-east-1.logs',
+        });
+        // Exactly one gateway endpoint (S3). Its ServiceName synthesizes as a
+        // region-tokenized Fn::Join, so assert by type/count rather than a literal.
+        const gateways = template.findResources(IFACE, { Properties: { VpcEndpointType: 'Gateway' } });
+        assert.equal(Object.keys(gateways).length, 1, 'exactly one gateway endpoint (S3)');
+        // SSM is NOT always-on — it flows from BB requirements only.
+        const ssm = template.findResources(IFACE, {
+            Properties: { ServiceName: 'com.amazonaws.us-east-1.ssm' },
+        });
+        assert.equal(Object.keys(ssm).length, 0, 'no SSM endpoint without a BB that needs it');
+    });
+    it('provisions the union of BB-declared endpoints plus the always-on Logs + S3', () => {
+        const template = synthWith((scope) => {
+            new FakeBB(scope, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+            new FakeBB(scope, 'Bucket', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.S3] });
+            new FakeBB(scope, 'Job', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+            new FakeBB(scope, 'Db', {
+                interfaceEndpoints: [
+                    ec2.InterfaceVpcEndpointAwsService.SECRETS_MANAGER,
+                    ec2.InterfaceVpcEndpointAwsService.RDS_DATA,
+                ],
+            });
+        });
+        const { iface, gateway } = endpointCounts(template);
+        // Gateways: DynamoDB + S3 (BB's S3 dedups with the always-on S3).
+        assert.equal(gateway, 2);
+        // Interfaces: SQS + Secrets Manager + RDS Data + always-on Logs.
+        assert.equal(iface, 4);
+    });
+    it('deduplicates endpoints requested by multiple BBs', () => {
+        const template = synthWith((scope) => {
+            new FakeBB(scope, 'Kv1', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+            new FakeBB(scope, 'Kv2', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+            new FakeBB(scope, 'Job1', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+            new FakeBB(scope, 'Job2', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+        });
+        const { iface, gateway } = endpointCounts(template);
+        // Two DynamoDB requests collapse to one; plus always-on S3 = 2 gateways.
+        assert.equal(gateway, 2);
+        // Two SQS requests collapse to one; plus always-on Logs = 2 interfaces.
+        assert.equal(iface, 2);
+    });
+    it('provisions SSM only when a BB declares it (and dedups multiple declarations)', () => {
+        const template = synthWith((scope) => {
+            new FakeBB(scope, 'AppSetting', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SSM] });
+            new FakeBB(scope, 'Auth', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SSM] });
+        });
+        const { iface } = endpointCounts(template);
+        // Two SSM requests collapse to one; plus always-on Logs = 2 interfaces.
+        assert.equal(iface, 2);
+        template.hasResourceProperties(IFACE, {
+            VpcEndpointType: 'Interface',
+            ServiceName: 'com.amazonaws.us-east-1.ssm',
+        });
+    });
+    it('provisions nothing when provisionEndpoints is false (but still validates requiresEgress)', () => {
+        const template = synthWith((scope) => {
+            new FakeBB(scope, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+        }, { provisionEndpoints: false });
+        template.resourceCountIs(IFACE, 0);
+    });
+    it('scopes the interface-endpoint SG to 443 from the Blocks Lambda SG only', () => {
+        const template = synthWith((scope) => {
+            new FakeBB(scope, 'Job', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+        });
+        // A dedicated endpoint SG exists, described as Lambda-scoped, with a 443
+        // ingress rule sourced from another SG (the Lambda SG) rather than the whole
+        // VPC CIDR. We assert the rule is present (arrayWith) rather than the exact
+        // array, since CDK may add its own paired rule for the endpoint association.
+        const sgs = template.findResources('AWS::EC2::SecurityGroup', {
+            Properties: { GroupDescription: 'Blocks interface VPC endpoints — 443 from the Blocks Lambda only' },
+        });
+        assert.equal(Object.keys(sgs).length, 1, 'exactly one dedicated endpoint SG');
+        const sg = Object.values(sgs)[0];
+        const ingress = sg.Properties.SecurityGroupIngress ?? [];
+        const https = ingress.filter((r) => r.FromPort === 443 && r.ToPort === 443);
+        assert.equal(https.length, 1, 'exactly one 443 ingress rule');
+        // Must NOT be open to a CIDR (that would be the broad default we're avoiding).
+        assert.equal(https[0].CidrIp, undefined, '443 ingress is SG-sourced, not CIDR-open');
+    });
+});
+describe('finalizeVpc — requiresEgress validation', () => {
+    it('passes when the runtime placement provides egress', () => {
+        // Default placement is private-with-egress, which provides egress.
+        assert.doesNotThrow(() => synthWith((scope) => {
+            new FakeBB(scope, 'Dsql', { requiresEgress: true });
+        }));
+    });
+    it('throws an actionable, BB-named error when the placement has no egress', () => {
+        // Place the runtime in isolated subnets; a BB needing egress cannot be served.
+        assert.throws(() => synthWith((scope) => {
+            new FakeBB(scope, 'Dsql', { requiresEgress: true });
+        }, { subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED } }), /Dsql requires its runtime to reach the internet.*no egress/s);
+    });
+    it('does not validate a BB that does not require egress', () => {
+        // A BB with no egress need is fine in isolated subnets.
+        assert.doesNotThrow(() => synthWith((scope) => {
+            new FakeBB(scope, 'Bb', {});
+        }, { subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED } }));
+    });
+});
+describe('initializeVpc — Lambda placement guard', () => {
+    function init(natGateways, subnets) {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'S', { env: { account: '123456789012', region: 'us-east-1' } });
+        const subnetConfiguration = natGateways === 0
+            ? [{ name: 'isolated', subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 }]
+            : undefined;
+        const vpc = new ec2.Vpc(stack, 'Vpc', { maxAzs: 2, natGateways, subnetConfiguration });
+        return () => initializeVpc(stack, { network: vpc, subnets });
+    }
+    it('throws an actionable error when defaulting to private-with-egress but the VPC has none', () => {
+        assert.throws(init(0), /no private-with-egress subnets.*NAT gateway/s);
+    });
+    it('does not throw when the VPC has a private-with-egress tier', () => {
+        assert.doesNotThrow(init(1));
+    });
+    it('honors an explicit isolated placement without the private-with-egress guard', () => {
+        // Caller explicitly chose isolated; the default-path guard must not fire.
+        assert.doesNotThrow(init(0, { subnetType: ec2.SubnetType.PRIVATE_ISOLATED }));
+    });
+});
+describe('VpcContext.selectSubnets — instructive resolution', () => {
+    function contextFor(natGateways) {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'S', { env: { account: '123456789012', region: 'us-east-1' } });
+        const vpc = new ec2.Vpc(stack, 'Vpc', { maxAzs: 2, natGateways });
+        // With natGateways: 0 CDK still creates the default public+private config,
+        // but the private tier becomes isolated (no NAT). Build an explicit
+        // isolated-only VPC to exercise the "no isolated" and "no egress" cases.
+        return initializeVpc(stack, { network: vpc, subnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS } });
+    }
+    it('returns the requested role when the VPC has it', () => {
+        const ctx = contextFor(1);
+        const sel = ctx.selectSubnets({ fullId: 'app/db' }, 'private-with-egress');
+        assert.equal(sel.subnetType, ec2.SubnetType.PRIVATE_WITH_EGRESS);
+    });
+    it('falls back to an explicit fallback role when the requested role is absent', () => {
+        const ctx = contextFor(1); // has public + private-with-egress, no isolated
+        const sel = ctx.selectSubnets({ fullId: 'app/db' }, 'isolated', { fallback: 'private-with-egress' });
+        assert.equal(sel.subnetType, ec2.SubnetType.PRIVATE_WITH_EGRESS);
+    });
+    it('throws a BB-named error when neither the role nor its fallback exists', () => {
+        const ctx = contextFor(1); // no isolated tier, and no public fallback requested that helps
+        assert.throws(() => ctx.selectSubnets({ fullId: 'app/db' }, 'isolated'), /app\/db needs a 'isolated' subnet.*has none/s);
+    });
+});
+// We can't fully test CDK constructs without a Stack, but we can test
+// the getVpcContext logic with mock constructs.
+describe('VPC utilities', () => {
+    it('getVpcContext returns undefined when no context set', () => {
+        const fakeScope = { node: { scope: undefined } };
+        assert.equal(getVpcContext(fakeScope), undefined);
+    });
+    it('getVpcContext walks up the scope tree', () => {
+        const vpcContext = { vpc: 'mock-vpc', computeSecurityGroup: 'mock-sg', computeSubnets: {} };
+        const parent = { node: { scope: undefined } };
+        setVpcContext(parent, vpcContext);
+        const child = { node: { scope: parent } };
+        assert.equal(getVpcContext(child), vpcContext);
+    });
+    it('setVpcContext stores context on the scope', () => {
+        const fakeScope = { node: { scope: undefined } };
+        const vpcContext = { vpc: 'mock-vpc', computeSecurityGroup: 'mock-sg', computeSubnets: {} };
+        setVpcContext(fakeScope, vpcContext);
+        assert.equal(getVpcContext(fakeScope), vpcContext);
+    });
+});
+describe('lazy VPC derivation', () => {
+    function stackWith(bbs) {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'LazyStack', { env: { account: '123456789012', region: 'us-east-1' } });
+        bbs(stack);
+        return { stack, scope: stack };
+    }
+    it('anyRequirementNeedsVpc is false for BBs that only declare endpoints', () => {
+        const { scope } = stackWith((s) => {
+            new FakeBB(s, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+            new FakeBB(s, 'Job', { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS] });
+        });
+        assert.equal(anyRequirementNeedsVpc(scope), false);
+    });
+    it('anyRequirementNeedsVpc is true when a BB declares requiresVpc', () => {
+        const { scope } = stackWith((s) => {
+            new FakeBB(s, 'Kv', { gatewayEndpoints: [ec2.GatewayVpcEndpointAwsService.DYNAMODB] });
+            new FakeBB(s, 'Container', { requiresVpc: true });
+        });
+        assert.equal(anyRequirementNeedsVpc(scope), true);
+    });
+    it('getOrCreateVpc returns the same VPC on repeated calls (singleton)', () => {
+        const { scope } = stackWith(() => { });
+        const a = getOrCreateVpc(scope);
+        const b = getOrCreateVpc(scope);
+        assert.equal(a, b, 'lazy VPC is a per-stack singleton');
+    });
+    it('a derived VPC + finalizeVpc provisions endpoints for a requiresVpc app', () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'DerivedStack', { env: { account: '123456789012', region: 'us-east-1' } });
+        new FakeBB(stack, 'Container', {
+            requiresVpc: true,
+            interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.SQS],
+        });
+        assert.equal(anyRequirementNeedsVpc(stack), true);
+        const vpc = getOrCreateVpc(stack);
+        const options = { network: vpc };
+        initializeVpc(stack, options);
+        finalizeVpc(stack, options);
+        const template = Template.fromStack(stack);
+        // SQS (from the BB) + always-on CloudWatch Logs interface endpoints, plus
+        // the always-on S3 gateway endpoint.
+        const { iface, gateway } = endpointCounts(template);
+        assert.equal(iface, 2, 'SQS + Logs');
+        assert.equal(gateway, 1, 'S3 gateway');
+    });
+});

package/dist/client/index.d.ts

@@ -92,6 +92,6 @@ export interface ApiNamespaceClientOptions {
  * ```
  */
 export declare function ApiNamespaceClient<T extends Record<string, (...args: any[]) => any>>(name: string, options?: ApiNamespaceClientOptions): AsyncAPI<T>;
-export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+export { ApiError, blocksError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export { Scope, type ScopeOptions } from '../common/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;AAiBhF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAoHF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iKAAiK;IACjK,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wHAAwH;IACxH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAqBD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAClF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,yBAAyB,GAClC,QAAQ,CAAC,CAAC,CAAC,CAyDb;AAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;AAiBhF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAoHF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iKAAiK;IACjK,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wHAAwH;IACxH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAqBD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAClF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,yBAAyB,GAClC,QAAQ,CAAC,CAAC,CAAC,CAyDb;AAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC1G,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/client/index.js

@@ -234,5 +234,5 @@ export function ApiNamespaceClient(name, options) {
         }
     });
 }
-export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
+export { ApiError, blocksError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
 export { Scope } from '../common/index.js';

package/dist/common/config.d.ts

@@ -34,6 +34,40 @@ export declare function preloadConfig(): Promise<void>;
  * Only sets env vars that aren't already set (won't override explicit env vars).
  */
 export declare function loadConfigToProcessEnv(): Promise<void>;
+/**
+ * Whether a config load has resolved and cached a result.
+ *
+ * Returns `true` once `loadConfigFromS3()` has cached a config object — either a
+ * successful S3 load, a genuinely-empty `{}` config, or the no-bucket local-dev
+ * path (both of which cache `{}`). Returns `false` in the initial state AND
+ * after a transient not-found miss: the 404 path deliberately does NOT cache its
+ * empty result (see `loadConfigFromS3`), so a `false` return immediately after
+ * awaiting a load uniquely identifies the post-deploy S3 window where
+ * blocks-config.json isn't readable yet.
+ *
+ * Callers use this to tell a transient-empty load (retry on the next request)
+ * apart from a legitimately-config-less app (do nothing) without reaching into
+ * the module's private cache.
+ */
+export declare function isConfigResolved(): boolean;
+/**
+ * Sanitize a Blocks identifier into a valid config/env-var key segment:
+ * uppercase, with every non-alphanumeric character replaced by `_`.
+ *
+ * Config entries are loaded into `process.env` at runtime (see
+ * {@link loadConfigToProcessEnv}), so a key must be a valid env-var name. This
+ * is the single rule both sides of a key share: whoever *writes* a config key
+ * (`registerConfig(\`PREFIX_${sanitizeConfigKey(id)}\`, …)`) and whoever *reads*
+ * it (`getConfigSync(\`PREFIX_${sanitizeConfigKey(id)}\`)`) MUST go through this
+ * function so they reconstruct a byte-identical key — a hand-inlined variant
+ * that drifts silently misses the lookup at runtime.
+ *
+ * @example
+ * ```typescript
+ * registerConfig(this, `BLOCKS_QUEUE_URL_${sanitizeConfigKey(this.fullId)}`, url);
+ * ```
+ */
+export declare function sanitizeConfigKey(id: string): string;
 /**
  * Reset the config cache. **For testing only.**
  */

package/dist/common/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AA4FA;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEtG"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AAgGA;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEtG"}