@aws-blocks/core 0.3.0 → 0.5.0

package/src/cdk/vpc.ts

@@ -0,0 +1,336 @@
+// 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 type { Construct } from 'constructs';
+import { getVpcRequirements as getRegisteredVpcRequirements } from './vpc-requirements-registry.js';
+import type { BlocksVpcOptions, SubnetRole, SubnetScope, VpcContext, VpcRequirements } from './vpc-types.js';
+
+const VPC_CONTEXT_KEY = Symbol.for('BLOCKS_VPC_CONTEXT');
+
+/** Map a subnet role to its concrete CDK subnet type. */
+function subnetTypeForRole(role: SubnetRole): ec2.SubnetType {
+	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: ec2.IVpc, role: SubnetRole): boolean {
+	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: Construct, context: VpcContext): void {
+	(scope as any)[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: Construct): VpcContext | undefined {
+	let current: Construct | undefined = scope;
+	while (current) {
+		const ctx = (current as any)[VPC_CONTEXT_KEY] as VpcContext | undefined;
+		if (ctx) return ctx;
+		current = current.node.scope as Construct | undefined;
+	}
+	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: Construct): boolean {
+	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: Construct): ec2.IVpc {
+	const holder = scope as any;
+	const existing = holder[LAZY_VPC_KEY] as ec2.IVpc | undefined;
+	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: Construct, options: BlocksVpcOptions): VpcContext {
+	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: VpcContext = {
+		vpc,
+		computeSecurityGroup,
+		computeSubnets: resolvedSubnets,
+		selectSubnets(scope: SubnetScope, role: SubnetRole, opts?: { fallback?: SubnetRole }): ec2.SubnetSelection {
+			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: Construct, options: BlocksVpcOptions): void {
+	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: boolean | undefined = placementProvidesEgress(vpc, subnets);
+
+	const gatewayEndpoints: ec2.GatewayVpcEndpointAwsService[] = [];
+	const interfaceEndpoints: ec2.InterfaceVpcEndpointAwsService[] = [];
+
+	// 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<string>();
+
+	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<string>();
+
+	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: ec2.IVpc, selection?: ec2.SubnetSelection): boolean | undefined {
+	// 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<string>([
+			...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/src/client/index.ts

@@ -316,5 +316,5 @@ export function ApiNamespaceClient<T extends Record<string, (...args: any[]) =>
   });
 }
 
-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';

package/src/common/config.test.ts

@@ -131,6 +131,27 @@ describe('config — S3 errors', () => {
 		assert.strictEqual(result, '', 'Should return empty string (empty config) on 404');
 	});
 
+	it('does not cache a not-found result — a later call re-fetches once the config exists', async () => {
+		process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+		process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+
+		// Simulate the transient post-deploy window: the object isn't written yet on the first
+		// fetch, then becomes available. A not-found result must NOT be cached, or the container
+		// would be poisoned with empty config for its lifetime.
+		let call = 0;
+		const notFound = new Error('The specified key does not exist.');
+		(notFound as any).name = 'NoSuchKey';
+		_setS3Fetcher(async () => {
+			call++;
+			if (call === 1) throw notFound;
+			return JSON.stringify({ READY_KEY: 'ready-value' });
+		});
+
+		assert.strictEqual(await getConfig('READY_KEY'), '', 'first call sees the not-yet-written config as empty');
+		assert.strictEqual(await getConfig('READY_KEY'), 'ready-value', 'later call re-fetches once the config exists');
+		assert.strictEqual(call, 2, 'a not-found result must not be cached — S3 is retried');
+	});
+
 	it('throws with clear message on S3 network error', async () => {
 		process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
 		process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';

package/src/common/config.ts

@@ -60,9 +60,13 @@ async function loadConfigFromS3(): Promise<Record<string, string>> {
 			|| error?.Code === 'NoSuchKey'
 			|| error?.$metadata?.httpStatusCode === 404;
 		if (isNotFound) {
-			console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config`);
-			configCache = {};
-			return configCache;
+			// Do NOT cache the empty result: a 404 right after deploy is usually the config file
+			// not being readable yet (the transient window before the BucketDeployment settles), not
+			// a genuinely config-less app. Caching {} here would poison the container for its whole
+			// lifetime. Returning without caching lets the next invocation re-fetch and pick up the
+			// real config once it's present. (Apps that truly have no config just re-check cheaply.)
+			console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config (will retry on next request)`);
+			return {};
 		}
 		const msg = error instanceof Error ? error.message : String(error);
 		throw new Error(`[Blocks] Failed to load config from S3 (${bucket}/${key}): ${msg}`);
@@ -152,6 +156,46 @@ export async 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 function isConfigResolved(): boolean {
+	return configCache !== null;
+}
+
+/**
+ * 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 function sanitizeConfigKey(id: string): string {
+	return id.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+
 /**
  * Reset the config cache. **For testing only.**
  */

package/src/common/index.ts

@@ -338,6 +338,14 @@ export interface BlocksStackProps extends StackProps {
 
 export class BlocksStack {
 	public readonly id: string;
+	/**
+	 * Path to the app's backend module (`props.backendCDKPath`). A typed contract for Building
+	 * Blocks that co-bundle the backend at synth time and read it off
+	 * `globalThis.CURRENT_BLOCKS_STACK` (the CDK `BlocksStack` / `BlocksBackend` set it). Declared
+	 * here so those consumers can type against this shared `BlocksStack` contract — which the CDK
+	 * `BlocksStack` / `BlocksBackend` implements — instead of `any`.
+	 */
+	declare readonly backendModulePath: string;
 	constructor(scope: Construct, id: string, props: BlocksStackProps) {
 		this.id = id;
 	}

package/src/errors.ts

@@ -48,6 +48,11 @@ export class ApiError extends Error {
 	 * when `retriable === true`; non-retriable errors (expired session,
 	 * tampered envelope, too-many-attempts lockouts) require restarting the
 	 * flow. Defaults to `false` when unspecified.
+	 *
+	 * This marks whether the *kind* of failure is retriable in principle, not a
+	 * guarantee that a given retry will succeed — e.g. an optimistic-lock
+	 * conflict against a missing row is flagged retriable, yet a blind retry
+	 * fails identically.
 	 */
 	readonly retriable: boolean;
 
@@ -78,6 +83,27 @@ export function isBlocksError<N extends string>(e: unknown, name: N): e is Error
 	return e instanceof Error && e.name === name;
 }
 
+/**
+ * Build a named `Error` whose `name` is a BB error constant, so it is matchable
+ * with {@link isBlocksError} on both server and client. The name is also
+ * prefixed into the message for readable logs.
+ *
+ * This is the producer half of the {@link isBlocksError} contract: throw via
+ * this helper so the `name` a consumer matches on is set consistently. It has
+ * no runtime dependencies, so it is safe to use in every bundle — mock,
+ * aws-runtime, and CDK synth.
+ *
+ * @example
+ * ```typescript
+ * throw blocksError(KVStoreErrors.ConditionalCheckFailed, 'Key already exists');
+ * ```
+ */
+export function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
 /**
  * Type guard for branching on a failed `AuthState` (the recommended
  * `setAuthState` client path) by its structured `errorName`.

package/src/hosting.test.ts

@@ -13,7 +13,7 @@ import { App, Duration, Stack } from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
 import { BLOCKS_RPC_PREFIX } from './constants.js';
 import { type BlocksStackApi, Hosting } from './hosting.js';
-import { clearRouteRegistry, registerRoute } from './raw-route.js';
+import { clearRouteRegistry, compilePath, registerRoute, type RegisteredRoute } from './raw-route.js';
 
 // ================================================================
 // Hosting construct tests
@@ -484,6 +484,34 @@ describe('Hosting', () => {
       }
       assert.ok(foundRetain, 'At least one bucket should have Retain deletion policy');
     });
+
+    it('forwards buildRetentionDays to the hosting bucket lifecycle rule (#480)', () => {
+      createSpaBuildOutput(tmpDir);
+
+      const app = new App();
+      const stack = new Stack(app, 'RetentionStack');
+
+      new Hosting(stack, 'Hosting', {
+        root: tmpDir,
+        api: MOCK_API,
+        buildRetentionDays: 90,
+      });
+
+      const template = Template.fromStack(stack);
+      // Before the fix, core dropped buildRetentionDays (only retainOnDelete was
+      // forwarded), so this asserted 30. It must now reach the DeleteOldBuilds
+      // rule as 90.
+      template.hasResourceProperties('AWS::S3::Bucket', {
+        LifecycleConfiguration: Match.objectLike({
+          Rules: Match.arrayWith([
+            Match.objectLike({
+              Id: 'DeleteOldBuilds',
+              ExpirationInDays: 90,
+            }),
+          ]),
+        }),
+      });
+    });
   });
 
   // ── API integration tests ────────────────────────────────────
@@ -708,6 +736,50 @@ describe('Hosting', () => {
       assert.ok(patterns.includes('/users/*'), 'Should have /users/* behavior for parameterized RawRoute');
     });
 
+    it('adds a CloudFront behavior for a route another core copy registered', () => {
+      createSpaBuildOutput(tmpDir);
+
+      // Synth has the same split as dispatch: a bundle can hold more than one
+      // copy of @aws-blocks/core, and this loop reads whichever route table
+      // its own copy owns. Register the way a second copy would — straight
+      // into the shared state, not through this copy's registerRoute() — and
+      // the behavior must still be emitted. With a module-local registry it
+      // never is, and the route 404s at CloudFront before Lambda is reached.
+      const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+      const state = (globalThis as typeof globalThis & { [REGISTRY_KEY]?: { routes: RegisteredRoute[] } })[
+        REGISTRY_KEY
+      ];
+      assert.ok(state, `route registry state must live on globalThis['${REGISTRY_KEY}']`);
+
+      const { pattern, paramNames } = compilePath('/from-other-copy');
+      state.routes.push({
+        method: 'GET',
+        path: '/from-other-copy',
+        pattern,
+        paramNames,
+        handler: async () => {},
+      });
+
+      const app = new App();
+      const stack = new Stack(app, 'ForeignRouteBehaviorStack');
+
+      new Hosting(stack, 'Hosting', {
+        root: tmpDir,
+        api: MOCK_API,
+      });
+
+      const template = Template.fromStack(stack);
+      const distributions = template.findResources('AWS::CloudFront::Distribution');
+      const distKeys = Object.keys(distributions);
+      const distConfig = (distributions[distKeys[0]] as any).Properties.DistributionConfig;
+      const patterns = (distConfig.CacheBehaviors ?? []).map((b: any) => b.PathPattern);
+
+      assert.ok(
+        patterns.includes('/from-other-copy'),
+        `synth must see routes from every core copy, got: ${JSON.stringify(patterns)}`,
+      );
+    });
+
     it('proxies the reserved /aws-blocks/auth subtree with a single behavior', () => {
       createSpaBuildOutput(tmpDir);
 
@@ -1540,6 +1612,20 @@ describe('Hosting', () => {
         `BlocksConfigDeployment must DependsOn the asset deployment(s); ` +
           `found DependsOn=${JSON.stringify(dependsOn)}`,
       );
+
+      const routeCutoverId = Object.entries(tpl.Resources).find(
+        ([id, resource]) =>
+          resource.Type === 'AWS::CloudFormation::CustomResource' &&
+          /RouteStoreKeys/.test(id),
+      )?.[0];
+      assert.ok(routeCutoverId, 'expected a RouteStoreKeys cutover resource');
+
+      const routeCutoverDeps = tpl.Resources[routeCutoverId].DependsOn ?? [];
+      assert.ok(
+        routeCutoverDeps.includes(configId),
+        `RouteStoreKeys must DependsOn BlocksConfigDeployment; ` +
+          `found DependsOn=${JSON.stringify(routeCutoverDeps)}`,
+      );
     });
   });
 

package/src/hosting.ts

@@ -264,6 +264,16 @@ export interface HostingProps {
   /** Retain the S3 bucket when the stack is deleted. Default: false. */
   retainOnDelete?: boolean;
 
+  /**
+   * Days to retain SUPERSEDED build artifacts in S3 before they are expired.
+   * Default: 30. The build currently referenced by CloudFront KVS (`meta.b`)
+   * is NEVER expired regardless of this value — only builds that have been
+   * replaced by a newer deploy are cleaned up (issue #480). Raise this to keep
+   * a longer rollback window. Must be at least `skewProtection.maxAge`
+   * (converted to days), or synth throws `InvalidSkewProtectionMaxAgeError`.
+   */
+  buildRetentionDays?: number;
+
   /** Custom Content-Security-Policy header value. */
   contentSecurityPolicy?: string;
 
@@ -671,7 +681,17 @@ export class Hosting extends Construct {
       environment: Object.keys(plainEnv).length ? plainEnv : undefined,
       domain: resolvedDomain,
       waf: props.waf,
-      storage: props.retainOnDelete != null ? { retainOnDelete: props.retainOnDelete } : undefined,
+      storage:
+        props.retainOnDelete != null || props.buildRetentionDays != null
+          ? {
+              ...(props.retainOnDelete != null
+                ? { retainOnDelete: props.retainOnDelete }
+                : {}),
+              ...(props.buildRetentionDays != null
+                ? { buildRetentionDays: props.buildRetentionDays }
+                : {}),
+            }
+          : undefined,
       cdn:
         props.contentSecurityPolicy || props.priceClass || props.geoRestriction || props.quotas
           ? {
@@ -768,6 +788,9 @@ export class Hosting extends Construct {
       for (const dep of assetDeployments) {
         configDeployment.node.addDependency(dep);
       }
+
+      // Delay route cutover until resolved config replaces the static placeholder.
+      hosting.addBuildAssetDependency(configDeployment);
     }
 
     // ── 9. Register public origin + CORS hosting origin into S3 config ──