@fjall/components-infrastructure 0.95.0 → 0.99.1

package/dist/lib/resources/aws/monitoring/clickhouseAlarms.js

@@ -0,0 +1,139 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { FilterPattern, MetricFilter } from "aws-cdk-lib/aws-logs";
+import { ALARM_DEFAULTS, registerAlarm, buildAlarmDescription } from "./alarmDefaults.js";
+const CLICKHOUSE_METRIC_NAMESPACE = "Fjall/ClickHouse";
+/**
+ * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
+ * two log-driven alarms:
+ *
+ * - **Stuck merges** — `client.ts` polls `system.merges` every 5 min and logs
+ *   `serverLogger.warn("ClickHouse", "Stuck merge detected")` when elapsed
+ *   exceeds 30 min. The metric filter on the webapp log group emits a count
+ *   metric per match; the alarm fires on Sum >= 1 over 5 min × 2 evaluations.
+ * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup
+ *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
+ *   that masked the original IAM-grant misconfiguration (see
+ *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ */
+export function createClickHouseAlarms(props) {
+    const { scope, instanceRole, asgName, alarmTopic, webappLogGroup, backupTaskLogGroup, config = {} } = props;
+    const alarms = [];
+    const snsAction = new SnsAction(alarmTopic);
+    const cpuAlarm = new Alarm(scope, "ClickHouseCpuAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse host CPU utilisation exceeds threshold", undefined),
+        metric: new Metric({
+            namespace: "AWS/EC2",
+            metricName: "CPUUtilization",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Average"
+        }),
+        threshold: config.cpuThreshold ?? 90,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(cpuAlarm, snsAction, alarms);
+    const memoryAlarm = new Alarm(scope, "ClickHouseMemoryAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse host memory utilisation exceeds threshold (CWAgent)", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "mem_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Average"
+        }),
+        threshold: config.memoryThreshold ?? 80,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(memoryAlarm, snsAction, alarms);
+    const diskWarnAlarm = new Alarm(scope, "ClickHouseDiskWarnAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse data volume above 70% used — plan growth response", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "disk_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: Duration.minutes(15),
+            statistic: "Average"
+        }),
+        threshold: config.diskWarnThreshold ?? 70,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(diskWarnAlarm, snsAction, alarms);
+    const diskCriticalAlarm = new Alarm(scope, "ClickHouseDiskCriticalAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse data volume above 85% used — imminent insert failures", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "disk_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: Duration.minutes(5),
+            statistic: "Average"
+        }),
+        threshold: config.diskCriticalThreshold ?? 85,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(diskCriticalAlarm, snsAction, alarms);
+    const stuckMergeMetricName = "ClickHouseStuckMergeCount";
+    new MetricFilter(scope, "ClickHouseStuckMergeMetricFilter", {
+        logGroup: webappLogGroup,
+        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
+        metricName: stuckMergeMetricName,
+        filterPattern: FilterPattern.literal('"Stuck merge detected"'),
+        metricValue: "1",
+        defaultValue: 0
+    });
+    const stuckMergeAlarm = new Alarm(scope, "ClickHouseStuckMergeAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse merge stuck > 30 min — investigate parts pressure or replica health", undefined),
+        metric: new Metric({
+            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+            metricName: stuckMergeMetricName,
+            period: Duration.minutes(5),
+            statistic: "Sum"
+        }),
+        threshold: 1,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(stuckMergeAlarm, snsAction, alarms);
+    const backupFailureMetricName = "ClickHouseBackupFailureCount";
+    new MetricFilter(scope, "ClickHouseBackupFailureMetricFilter", {
+        logGroup: backupTaskLogGroup,
+        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
+        metricName: backupFailureMetricName,
+        filterPattern: FilterPattern.anyTerm("AccessDenied", "S3Exception"),
+        metricValue: "1",
+        defaultValue: 0
+    });
+    const backupFailureAlarm = new Alarm(scope, "ClickHouseBackupFailureAlarm", {
+        alarmDescription: buildAlarmDescription(`ClickHouse BACKUP TO S3 emitted AccessDenied/S3Exception — verify instance role '${instanceRole.roleName}' grant on backup bucket`, undefined),
+        metric: new Metric({
+            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+            metricName: backupFailureMetricName,
+            period: Duration.hours(1),
+            statistic: "Sum"
+        }),
+        threshold: 1,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(backupFailureAlarm, snsAction, alarms);
+    return alarms;
+}

package/dist/lib/resources/aws/monitoring/index.d.ts

@@ -2,3 +2,5 @@ export { ALARM_DEFAULTS, APPLICATION_ID_TAG_KEY, registerAlarm, tagAlarmsWithApp
 export { createEcsServiceAlarms, type EcsServiceAlarmThresholds, type EcsServiceAlarmsProps } from "./ecsAlarms.js";
 export { createRdsAlarms, type RdsAlarmThresholds, type RdsAlarmsProps } from "./rdsAlarms.js";
 export { createLambdaAlarms, type LambdaAlarmThresholds, type LambdaAlarmsProps } from "./lambdaAlarms.js";
+export { createScheduleAlarms, type ScheduleAlarmThresholds, type CreateScheduleAlarmsProps } from "./scheduleAlarms.js";
+export { createClickHouseAlarms, type ClickHouseAlarmThresholds, type ClickHouseAlarmsProps } from "./clickhouseAlarms.js";

package/dist/lib/resources/aws/monitoring/index.js

@@ -2,3 +2,5 @@ export { ALARM_DEFAULTS, APPLICATION_ID_TAG_KEY, registerAlarm, tagAlarmsWithApp
 export { createEcsServiceAlarms } from "./ecsAlarms.js";
 export { createRdsAlarms } from "./rdsAlarms.js";
 export { createLambdaAlarms } from "./lambdaAlarms.js";
+export { createScheduleAlarms } from "./scheduleAlarms.js";
+export { createClickHouseAlarms } from "./clickhouseAlarms.js";

package/dist/lib/resources/aws/monitoring/scheduleAlarms.d.ts

@@ -0,0 +1,47 @@
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IRule } from "aws-cdk-lib/aws-events";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { Construct } from "constructs";
+/**
+ * Tunable thresholds for the EventBridge schedule alarms. Lives here (NOT in
+ * `messaging/schedule.ts`) so the consumer module — `eventBridgeRule.ts` /
+ * `Schedule` — can re-export it without forming a circular import.
+ */
+export interface ScheduleAlarmThresholds {
+    failedInvocationsThreshold?: number;
+    throttledRulesThreshold?: number;
+    dlqFailureThreshold?: number;
+    /**
+     * Multiplier applied to `expectedTicksPerHour` to derive the missed-tick
+     * floor. Default 0.8 — fires when observed matches drop below 80% of the
+     * expected cadence (silent disablement detector).
+     */
+    matchedEventsLowFloorRatio?: number;
+}
+export interface CreateScheduleAlarmsProps {
+    scope: Construct;
+    ruleName: string;
+    rule: IRule;
+    kind: "schedule" | "subscription";
+    /** Populated by `parseRateExpression(...)` — undefined for cron schedules and subscriptions. */
+    expectedTicksPerHour?: number;
+    config?: ScheduleAlarmThresholds;
+    alarmTopic: ITopic;
+    applicationId?: string;
+    dlqEnabled: boolean;
+}
+/**
+ * Provisions D13 alarms for an EventBridge rule. Returns the created alarms
+ * (each wired to the SNS topic for both ALARM and OK transitions and tagged
+ * with the application id for webhook routing).
+ *
+ * Alarm coverage:
+ *   - `FailedInvocations` / `ThrottledRules` always fire.
+ *   - `InvocationsFailedToBeSentToDlq` fires only when `dlqEnabled === true`.
+ *   - `MatchedEvents` (missed-tick detector) fires only when
+ *     `kind === "schedule"` AND `expectedTicksPerHour !== undefined` —
+ *     i.e. rate expressions, not cron, not subscriptions. Uses
+ *     `LessThanThreshold` + `treatMissingData: BREACHING` so a fully silent
+ *     rule trips the alarm.
+ */
+export declare function createScheduleAlarms(props: CreateScheduleAlarmsProps): Alarm[];

package/dist/lib/resources/aws/monitoring/scheduleAlarms.js

@@ -0,0 +1,106 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, TreatMissingData, Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { ALARM_DEFAULTS, registerAlarm, tagAlarmsWithApplicationId, buildAlarmDescription } from "./alarmDefaults.js";
+const DEFAULT_THRESHOLDS = {
+    FAILED_INVOCATIONS: 1,
+    THROTTLED_RULES: 1,
+    DLQ_FAILURE: 1,
+    MATCHED_EVENTS_LOW_FLOOR_RATIO: 0.8
+};
+/**
+ * Provisions D13 alarms for an EventBridge rule. Returns the created alarms
+ * (each wired to the SNS topic for both ALARM and OK transitions and tagged
+ * with the application id for webhook routing).
+ *
+ * Alarm coverage:
+ *   - `FailedInvocations` / `ThrottledRules` always fire.
+ *   - `InvocationsFailedToBeSentToDlq` fires only when `dlqEnabled === true`.
+ *   - `MatchedEvents` (missed-tick detector) fires only when
+ *     `kind === "schedule"` AND `expectedTicksPerHour !== undefined` —
+ *     i.e. rate expressions, not cron, not subscriptions. Uses
+ *     `LessThanThreshold` + `treatMissingData: BREACHING` so a fully silent
+ *     rule trips the alarm.
+ */
+export function createScheduleAlarms(props) {
+    const { scope, ruleName, rule, kind, expectedTicksPerHour, config = {}, alarmTopic, applicationId, dlqEnabled } = props;
+    const alarms = [];
+    const snsAction = new SnsAction(alarmTopic);
+    const failedInvocationsThreshold = config.failedInvocationsThreshold ?? DEFAULT_THRESHOLDS.FAILED_INVOCATIONS;
+    const throttledRulesThreshold = config.throttledRulesThreshold ?? DEFAULT_THRESHOLDS.THROTTLED_RULES;
+    const dlqFailureThreshold = config.dlqFailureThreshold ?? DEFAULT_THRESHOLDS.DLQ_FAILURE;
+    const matchedEventsLowFloorRatio = config.matchedEventsLowFloorRatio ??
+        DEFAULT_THRESHOLDS.MATCHED_EVENTS_LOW_FLOOR_RATIO;
+    const ruleDimensions = { RuleName: rule.ruleName };
+    const failedInvocationsAlarm = new Alarm(scope, `${ruleName}FailedInvocationsAlarm`, {
+        alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} FailedInvocations exceeds ${failedInvocationsThreshold}`, applicationId),
+        metric: new Metric({
+            namespace: "AWS/Events",
+            metricName: "FailedInvocations",
+            dimensionsMap: ruleDimensions,
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Sum"
+        }),
+        threshold: failedInvocationsThreshold,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(failedInvocationsAlarm, snsAction, alarms);
+    const throttledRulesAlarm = new Alarm(scope, `${ruleName}ThrottledRulesAlarm`, {
+        alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} ThrottledRules exceeds ${throttledRulesThreshold}`, applicationId),
+        metric: new Metric({
+            namespace: "AWS/Events",
+            metricName: "ThrottledRules",
+            dimensionsMap: ruleDimensions,
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Sum"
+        }),
+        threshold: throttledRulesThreshold,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(throttledRulesAlarm, snsAction, alarms);
+    if (dlqEnabled) {
+        const dlqFailureAlarm = new Alarm(scope, `${ruleName}DlqFailureAlarm`, {
+            alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} InvocationsFailedToBeSentToDlq exceeds ${dlqFailureThreshold}`, applicationId),
+            metric: new Metric({
+                namespace: "AWS/Events",
+                metricName: "InvocationsFailedToBeSentToDlq",
+                dimensionsMap: ruleDimensions,
+                period: Duration.minutes(5),
+                statistic: "Sum"
+            }),
+            threshold: dlqFailureThreshold,
+            evaluationPeriods: 1,
+            datapointsToAlarm: 1,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+        registerAlarm(dlqFailureAlarm, snsAction, alarms);
+    }
+    if (kind === "schedule" && expectedTicksPerHour !== undefined) {
+        const floor = Math.max(1, Math.floor(expectedTicksPerHour * matchedEventsLowFloorRatio));
+        const matchedEventsAlarm = new Alarm(scope, `${ruleName}MatchedEventsAlarm`, {
+            alarmDescription: buildAlarmDescription(`EventBridge rule ${ruleName} expected >=${floor} ticks/hour, observed <=${Math.round(matchedEventsLowFloorRatio * 100)}% threshold = silent disablement detector`, applicationId),
+            metric: new Metric({
+                namespace: "AWS/Events",
+                metricName: "MatchedEvents",
+                dimensionsMap: ruleDimensions,
+                period: Duration.hours(1),
+                statistic: "Sum"
+            }),
+            threshold: floor,
+            evaluationPeriods: 1,
+            datapointsToAlarm: 1,
+            comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+            treatMissingData: TreatMissingData.BREACHING
+        });
+        registerAlarm(matchedEventsAlarm, snsAction, alarms);
+    }
+    tagAlarmsWithApplicationId(alarms, applicationId);
+    return alarms;
+}

package/dist/lib/resources/aws/networking/crossAccountDelegationRecord.js

@@ -1,6 +1,7 @@
 import { Construct } from "constructs";
 import { Tags } from "aws-cdk-lib";
 import { CrossAccountZoneDelegationRecord as CdkCrossAccountZoneDelegationRecord } from "aws-cdk-lib/aws-route53";
+import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 // CDK's CrossAccountZoneDelegationRecord is a custom-resource Lambda: user-level tags
 // on the record itself may not reach AWS. We tag the wrapping Fjall Construct for
 // assertion purposes; create-path tags still propagate to child resources (Lambda,
@@ -19,8 +20,10 @@ export class CrossAccountDelegationRecord extends Construct {
             parentHostedZoneName: props.parentHostedZoneName
         });
         Tags.of(this).add("fjall:description", this.description);
-        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? "management");
-        Tags.of(this).add("fjall:costAllocation:service", "crossAccountDelegation");
-        Tags.of(this).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.delegatedZoneName);
+        applyCostAllocationTags(this, {
+            service: "crossAccountDelegation",
+            domain: props.costAllocationDomain ?? props.delegatedZoneName,
+            environment: props.costAllocationEnvironment
+        });
     }
 }

package/dist/lib/resources/aws/networking/crossAccountReturnRoutes.d.ts

@@ -0,0 +1,40 @@
+import { Construct } from "constructs";
+import { CustomResource } from "../utilities/customResource.js";
+/**
+ * Properties for {@link CrossAccountReturnRoutes}.
+ *
+ * The route-table IDs are passed as a comma-joined string because CloudFormation
+ * custom-resource properties are flat strings. Inside the handler (which runs
+ * after CFN token resolution) the string is split back into an array.
+ */
+export interface CrossAccountReturnRoutesProps {
+    /** ARN of the accepter-account role the Lambda assumes to make EC2 calls. */
+    readonly peerRoleArn: string;
+    /** Region of the accepter VPC (so the EC2 client targets the correct region). */
+    readonly peerRegion: string;
+    /** Route-table IDs in the accepter VPC that should receive return routes. */
+    readonly routeTableIds: string[];
+    /** Local VPC CIDR — destination of the return routes in the accepter's tables. */
+    readonly localVpcCidr: string;
+    /** The peering connection ID (the target of the return routes). */
+    readonly peeringConnectionId: string;
+    /** Whether to also set `AccepterPeeringConnectionOptions.AllowDnsResolutionFromRemoteVpc`. */
+    readonly enableDns?: boolean;
+}
+/**
+ * Cross-account return-route manager for a VPC peering connection.
+ *
+ * Uses the shared {@link CustomResource} wrapper with an inline Lambda handler.
+ * The Lambda's execution role is local to the requester account — it holds only
+ * `sts:AssumeRole` on the accepter role. All EC2 calls happen under the assumed
+ * credentials in the accepter account.
+ *
+ * Create paths add `CreateRouteCommand` entries per route-table ID; delete
+ * paths reverse them via `DeleteRouteCommand`. When `enableDns` is true the
+ * handler additionally calls `ModifyVpcPeeringConnectionOptionsCommand` on the
+ * accepter side so DNS resolution works bidirectionally.
+ */
+export declare class CrossAccountReturnRoutes extends Construct {
+    readonly customResource: CustomResource;
+    constructor(scope: Construct, id: string, props: CrossAccountReturnRoutesProps);
+}

package/dist/lib/resources/aws/networking/crossAccountReturnRoutes.js

@@ -0,0 +1,158 @@
+import { Construct } from "constructs";
+import { Duration, Fn } from "aws-cdk-lib";
+import { Runtime } from "aws-cdk-lib/aws-lambda";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { CustomResource } from "../utilities/customResource.js";
+/**
+ * Cross-account return-route manager for a VPC peering connection.
+ *
+ * Uses the shared {@link CustomResource} wrapper with an inline Lambda handler.
+ * The Lambda's execution role is local to the requester account — it holds only
+ * `sts:AssumeRole` on the accepter role. All EC2 calls happen under the assumed
+ * credentials in the accepter account.
+ *
+ * Create paths add `CreateRouteCommand` entries per route-table ID; delete
+ * paths reverse them via `DeleteRouteCommand`. When `enableDns` is true the
+ * handler additionally calls `ModifyVpcPeeringConnectionOptionsCommand` on the
+ * accepter side so DNS resolution works bidirectionally.
+ */
+export class CrossAccountReturnRoutes extends Construct {
+    customResource;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.customResource = new CustomResource(this, "Handler", {
+            runtime: Runtime.NODEJS_22_X,
+            timeout: Duration.minutes(5),
+            lambdaDescription: `${id} cross-account return-route manager`,
+            roleDescription: `${id} return-route Lambda execution role`,
+            inlinePolicy: [
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["sts:AssumeRole"],
+                    resources: [props.peerRoleArn]
+                })
+            ],
+            properties: {
+                PeerRoleArn: props.peerRoleArn,
+                PeerRegion: props.peerRegion,
+                RouteTableIds: Fn.join(",", props.routeTableIds),
+                LocalVpcCidr: props.localVpcCidr,
+                PeeringConnectionId: props.peeringConnectionId,
+                EnableDns: props.enableDns === false ? "false" : "true"
+            },
+            inlineCode: HANDLER_SOURCE
+        });
+    }
+}
+// Handler source. Inline because the CustomResource utility expects a string;
+// extracting to its own file would require switching to a bundled asset.
+const HANDLER_SOURCE = `
+const { STSClient, AssumeRoleCommand } = require("@aws-sdk/client-sts");
+const {
+  EC2Client,
+  CreateRouteCommand,
+  DeleteRouteCommand,
+  ModifyVpcPeeringConnectionOptionsCommand
+} = require("@aws-sdk/client-ec2");
+
+async function buildAccepterClient(props) {
+  const sts = new STSClient({});
+  const assumed = await sts.send(new AssumeRoleCommand({
+    RoleArn: props.PeerRoleArn,
+    RoleSessionName: "fjall-vpc-peer-return-routes"
+  }));
+  const creds = assumed.Credentials;
+  if (!creds || !creds.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) {
+    throw new Error("AssumeRole returned no credentials");
+  }
+  return new EC2Client({
+    region: props.PeerRegion,
+    credentials: {
+      accessKeyId: creds.AccessKeyId,
+      secretAccessKey: creds.SecretAccessKey,
+      sessionToken: creds.SessionToken
+    }
+  });
+}
+
+function parseRouteTableIds(value) {
+  if (!value) return [];
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+exports.handler = async (event) => {
+  const props = event.ResourceProperties || {};
+  const physicalResourceId = event.PhysicalResourceId || event.LogicalResourceId || "return-routes";
+  const routeTableIds = parseRouteTableIds(props.RouteTableIds);
+  const ec2 = await buildAccepterClient(props);
+
+  if (event.RequestType === "Delete") {
+    for (const routeTableId of routeTableIds) {
+      try {
+        await ec2.send(new DeleteRouteCommand({
+          RouteTableId: routeTableId,
+          DestinationCidrBlock: props.LocalVpcCidr
+        }));
+      } catch (err) {
+        const name = err && err.name;
+        if (name === "InvalidRoute.NotFound" || name === "InvalidRouteTableID.NotFound") {
+          continue;
+        }
+        throw err;
+      }
+    }
+    return { PhysicalResourceId: physicalResourceId };
+  }
+
+  if (event.RequestType === "Update") {
+    const oldProps = event.OldResourceProperties || {};
+    const oldRouteTableIds = parseRouteTableIds(oldProps.RouteTableIds);
+    const oldCidr = oldProps.LocalVpcCidr || props.LocalVpcCidr;
+    const cidrChanged = oldCidr !== props.LocalVpcCidr;
+    const currentSet = new Set(routeTableIds);
+    // CIDR change: stale routes persist on every kept table unless deleted by old CIDR first.
+    const idsToDeleteOldCidr = cidrChanged
+      ? oldRouteTableIds
+      : oldRouteTableIds.filter((id) => !currentSet.has(id));
+    for (const routeTableId of idsToDeleteOldCidr) {
+      try {
+        await ec2.send(new DeleteRouteCommand({
+          RouteTableId: routeTableId,
+          DestinationCidrBlock: oldCidr
+        }));
+      } catch (err) {
+        const name = err && err.name;
+        if (name === "InvalidRoute.NotFound" || name === "InvalidRouteTableID.NotFound") {
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  for (const routeTableId of routeTableIds) {
+    try {
+      await ec2.send(new CreateRouteCommand({
+        RouteTableId: routeTableId,
+        DestinationCidrBlock: props.LocalVpcCidr,
+        VpcPeeringConnectionId: props.PeeringConnectionId
+      }));
+    } catch (err) {
+      const name = err && err.name;
+      if (name !== "RouteAlreadyExists") {
+        throw err;
+      }
+    }
+  }
+
+  // Always sent so a flip from true to false actually disables DNS — guarding on === "true" leaves it enabled forever.
+  await ec2.send(new ModifyVpcPeeringConnectionOptionsCommand({
+    VpcPeeringConnectionId: props.PeeringConnectionId,
+    AccepterPeeringConnectionOptions: {
+      AllowDnsResolutionFromRemoteVpc: props.EnableDns === "true"
+    }
+  }));
+
+  return { PhysicalResourceId: physicalResourceId };
+};
+`.trim();

package/dist/lib/resources/aws/networking/dnsRecord/dnsRecordBase.js

@@ -1,5 +1,6 @@
-import { Duration, Tags } from "aws-cdk-lib";
+import { Duration } from "aws-cdk-lib";
 import { DNS_APEX } from "@fjall/util";
+import { applyCostAllocationTags } from "../../../../utils/costAllocationTags.js";
 export const DEFAULT_DNS_TTL_SECONDS = 300;
 export function resolveFqdn(zoneName, recordName) {
     return recordName === DNS_APEX ? zoneName : `${recordName}.${zoneName}`;
@@ -11,7 +12,9 @@ export function defaultDnsComment(recordType, fqdn) {
     return `Fjall-managed ${recordType} record for ${fqdn}`;
 }
 export function applyDnsRecordTags(construct, props) {
-    Tags.of(construct).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? "management");
-    Tags.of(construct).add("fjall:costAllocation:service", "dnsRecord");
-    Tags.of(construct).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.zoneName);
+    applyCostAllocationTags(construct, {
+        service: "dnsRecord",
+        domain: props.costAllocationDomain ?? props.zoneName,
+        environment: props.costAllocationEnvironment
+    });
 }

package/dist/lib/resources/aws/networking/domainCertificate.d.ts

@@ -1,5 +1,5 @@
 import { Construct } from "constructs";
-import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
+import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type IHostedZone } from "aws-cdk-lib/aws-route53";
 export interface DomainCertificateProps {
     readonly domainName: string;
@@ -11,7 +11,7 @@ export interface DomainCertificateProps {
     readonly costAllocationDomain?: string;
 }
 export declare class DomainCertificate extends Construct {
-    readonly certificate: Certificate;
+    readonly certificate: ICertificate;
     readonly certificateArn: string;
     readonly description: string;
     constructor(scope: Construct, id: string, props: DomainCertificateProps);

package/dist/lib/resources/aws/networking/domainCertificate.js

@@ -3,6 +3,7 @@ import { CfnOutput, Tags } from "aws-cdk-lib";
 import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { getDomainExportNames } from "@fjall/util";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
+import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 export class DomainCertificate extends Construct {
     certificate;
     certificateArn;
@@ -20,9 +21,11 @@ export class DomainCertificate extends Construct {
         });
         this.certificateArn = this.certificate.certificateArn;
         Tags.of(this).add("fjall:description", this.description);
-        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? "management");
-        Tags.of(this).add("fjall:costAllocation:service", "certificate");
-        Tags.of(this).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.domainName);
+        applyCostAllocationTags(this, {
+            service: "certificate",
+            domain: props.costAllocationDomain ?? props.domainName,
+            environment: props.costAllocationEnvironment
+        });
         const safeKey = toPascalCase(props.domainName.split(".").join(""));
         const exports = getDomainExportNames(props.domainName);
         new CfnOutput(this, `${safeKey}CertificateArn`, {

package/dist/lib/resources/aws/networking/hostedZone.js

@@ -4,6 +4,7 @@ import { HostedZone as AWSHostedZone } from "aws-cdk-lib/aws-route53";
 import { getDomainExportNames } from "@fjall/util";
 import { toPascalCase, getSafeZoneName } from "../../../utils/capitaliseString.js";
 import { DelegationRole } from "../iam/delegationRole.js";
+import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
 export class HostedZoneFactory {
     static import(stack, hostedZoneId, zoneName, opts) {
         const safeZone = toPascalCase(getSafeZoneName(zoneName));
@@ -70,10 +71,11 @@ export class HostedZone extends Construct {
             this.isImported = true;
             Tags.of(this).add("fjall:description", this.description);
         }
-        // Cost allocation tags applied uniformly on both create and import paths.
-        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? "management");
-        Tags.of(this).add("fjall:costAllocation:service", "hostedZone");
-        Tags.of(this).add("fjall:costAllocation:domain", props.costAllocationDomain ?? props.zoneName);
+        applyCostAllocationTags(this, {
+            service: "hostedZone",
+            domain: props.costAllocationDomain ?? props.zoneName,
+            environment: props.costAllocationEnvironment
+        });
         new CfnOutput(this, `${safeZone}HostedZoneId`, {
             key: `${safeZone}HostedZoneId`,
             value: this.hostedZoneId,

package/dist/lib/resources/aws/networking/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./crossAccountDelegationRecord.js";
+export * from "./crossAccountReturnRoutes.js";
 export * from "./dnsRecord/index.js";
 export * from "./domainCertificate.js";
 export * from "./hostedZone.js";
@@ -6,3 +7,5 @@ export * from "./ipam.js";
 export * from "./ipamPool.js";
 export * from "./securityGroup.js";
 export * from "./vpc.js";
+export * from "./vpcPeeringAccepterRole.js";
+export * from "./vpcPeeringConnection.js";

package/dist/lib/resources/aws/networking/index.js

@@ -1,4 +1,5 @@
 export * from "./crossAccountDelegationRecord.js";
+export * from "./crossAccountReturnRoutes.js";
 export * from "./dnsRecord/index.js";
 export * from "./domainCertificate.js";
 export * from "./hostedZone.js";
@@ -6,3 +7,5 @@ export * from "./ipam.js";
 export * from "./ipamPool.js";
 export * from "./securityGroup.js";
 export * from "./vpc.js";
+export * from "./vpcPeeringAccepterRole.js";
+export * from "./vpcPeeringConnection.js";