@fjall/components-infrastructure 0.94.1 → 0.96.0

package/dist/lib/patterns/aws/computeEcsTypes.d.ts

@@ -0,0 +1,386 @@
+import { type Repository } from "aws-cdk-lib/aws-ecr";
+import { type RepositoryImage } from "aws-cdk-lib/aws-ecs";
+import { type IVpc } from "aws-cdk-lib/aws-ec2";
+import { type PolicyDocument, type IManagedPolicy } from "aws-cdk-lib/aws-iam";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import { type ConnectionSpec } from "./interfaces/connector.js";
+import { type RemoteConnectionSpec } from "../../resources/aws/compute/ecsRemoteConnections.js";
+import { type EcsRoutingConfig } from "../../resources/aws/compute/ecsTypes.js";
+import { ScalingType, type DomainConfig, type EcsCapacityProvider, type Ec2CapacityConfig } from "../../resources/aws/compute/ecs.js";
+import type { EcsServiceAlarmThresholds } from "../../resources/aws/monitoring/index.js";
+import { type SecretImport } from "../../resources/aws/secrets/index.js";
+export type { RemoteConnectionSpec };
+export { ScalingType };
+export type { EcsCapacityProvider, Ec2CapacityConfig };
+/**
+ * Configuration for ECS capacity providers.
+ */
+export interface EcsCapacityProviderConfig {
+    /** Whether this uses Spot pricing */
+    usesSpot: boolean;
+    /** Whether this runs on EC2 instances (vs serverless Fargate) */
+    usesEc2Instances: boolean;
+}
+/**
+ * Configuration for a container in an ECS task.
+ *
+ * For single-container services, `name` is optional and defaults to `${serviceName}Container`.
+ * For multi-container tasks, the first container with a `port` is the **primary container**
+ * that receives load balancer traffic.
+ *
+ * @example
+ * // Single container (name auto-generated)
+ * containers: [{ port: 3000 }]
+ *
+ * @example
+ * // Multi-container with sidecars
+ * containers: [
+ *   { name: "app", port: 3000 },                    // Primary - receives ALB traffic
+ *   { name: "datadog", image: "datadog/agent" }     // Sidecar - monitoring
+ * ]
+ */
+export interface EcsContainerConfig {
+    /** Container name. Optional for single-container services. */
+    name?: string;
+    /**
+     * Container image. Options:
+     * - Omit: Uses app's default ECR repository (primary container only)
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
+     */
+    image?: string | Repository;
+    /**
+     * Port the container listens on.
+     * The first container with a port becomes the **primary container**
+     * and is registered with the load balancer.
+     */
+    port?: number;
+    /** Environment variables */
+    environment?: Record<string, string>;
+    /**
+     * Secrets from AWS SSM Parameter Store.
+     * Array of secret names that will be fetched from the service's SSM namespace.
+     * The namespace path is auto-determined from app/cluster/service names.
+     *
+     * @example
+     * // Secrets at /myapp/api-cluster/users/API_KEY and /myapp/api-cluster/users/DB_PASSWORD
+     * secrets: ["API_KEY", "DB_PASSWORD"]
+     */
+    secrets?: string[];
+    /** Secrets imported from other CDK resources (AWS Secrets Manager) */
+    secretsImport?: Record<string, SecretImport>;
+    /** Command to run in the container */
+    command?: string[];
+    /** Entry point for the container */
+    entryPoint?: string[];
+    /**
+     * Whether this container is essential.
+     * If an essential container stops, all containers in the task stop.
+     * Default: true
+     */
+    essential?: boolean;
+    /**
+     * Health check configuration.
+     * Default: For primary container with port, uses curl health check.
+     */
+    healthCheck?: {
+        command: string[];
+        interval?: number;
+        timeout?: number;
+        retries?: number;
+        startPeriod?: number;
+    };
+}
+/**
+ * ECS scaling configuration.
+ * - Omit: enabled with defaults
+ * - `{}`: enabled with defaults
+ * - `{ minCapacity: 2, maxCapacity: 10 }`: custom scaling
+ * - `false`: explicitly disabled
+ */
+export interface EcsScalingConfig {
+    minCapacity?: number;
+    maxCapacity?: number;
+    scalingType?: ScalingType;
+}
+/**
+ * Cluster-level configuration.
+ * Controls the shared ALB for all services in this cluster.
+ */
+export interface EcsClusterConfig {
+    /**
+     * Domain for HTTPS access.
+     * - Omit: ALB created with default DNS (*.elb.amazonaws.com)
+     * - Specified: Creates ACM certificate + Route53 DNS A record
+     */
+    domain?: string;
+    /**
+     * Load balancer configuration.
+     * - Omit or "public": Internet-facing ALB (default)
+     * - "internal": VPC-only ALB
+     * - false: No ALB (for workers/background processors)
+     */
+    loadBalancer?: false | "public" | "internal";
+    /**
+     * Enable direct EC2 access without ALB.
+     * Uses host network mode for predictable ports.
+     * Access via EC2 public IP at container port.
+     */
+    directAccess?: boolean;
+    /**
+     * Advanced domain configuration for routing policies (latency, weighted, geo).
+     * Only used when domain is specified.
+     * Allows for multi-region deployments with advanced DNS routing.
+     */
+    domainConfig?: DomainConfig;
+}
+export type { EcsRoutingConfig };
+/**
+ * Configuration for a service in an ECS cluster.
+ * Each service gets its own task definition, scaling config, and target group.
+ *
+ * @example
+ * // Simple service
+ * { name: "api", containers: [{ port: 3000 }] }
+ *
+ * @example
+ * // Service with routing (for multi-service clusters)
+ * { name: "users", containers: [{ port: 3000 }], routing: { path: "/users/*", priority: 100 } }
+ *
+ * @example
+ * // Service with multiple routing rules (same target group)
+ * { name: "web", containers: [{ port: 3000 }], routing: [
+ *   { path: "/api/v2/*", priority: 50 },
+ *   { path: "/*", priority: 200 },
+ * ]}
+ *
+ * @example
+ * // Service with sidecars
+ * {
+ *   name: "api",
+ *   containers: [
+ *     { name: "app", port: 3000 },
+ *     { name: "datadog", image: "datadog/agent" }
+ *   ]
+ * }
+ */
+export interface EcsServiceConfig {
+    /** Service name (unique within cluster) */
+    name: string;
+    /**
+     * Container image for this service (applies to first container without explicit image).
+     * - Omit: Uses app's default ECR repository
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
+     */
+    image?: string | Repository;
+    /**
+     * Container configuration(s) for this service.
+     * For single-container services, container name is optional and auto-generated.
+     * For multi-container services, the first container with a port is the primary container.
+     */
+    containers?: EcsContainerConfig[];
+    /**
+     * Routing rules for this service on the cluster's ALB.
+     * Required when cluster has multiple services with ports.
+     * Optional for single service (gets /* automatically).
+     * Can be a single rule or an array of rules pointing to the same target group.
+     *
+     * @example
+     * // Multiple routes for the same service
+     * routing: [
+     *   { path: "/api/v2/*", priority: 50 },
+     *   { path: "/*", priority: 200 },
+     * ]
+     */
+    routing?: EcsRoutingConfig | EcsRoutingConfig[];
+    /** CPU units for this service's tasks (256-4096) */
+    cpu?: number;
+    /** Memory in MiB for this service's tasks (512-30720) */
+    memoryLimitMiB?: number;
+    /** Desired number of tasks. Default: 2 */
+    desiredCount?: number;
+    /**
+     * Scaling configuration.
+     * - Omit: enabled with defaults
+     * - false: disabled
+     */
+    scaling?: EcsScalingConfig | false;
+    /**
+     * Path to Dockerfile for building this service's image.
+     * Metadata for CLI build process, not used during CDK synthesis.
+     */
+    dockerfilePath?: string;
+    /**
+     * Docker build target stage for multi-stage Dockerfiles.
+     * When specified, the CLI builds with `--target <dockerTarget>`.
+     * The image tag suffix is also updated: `<service>-<target>-latest`.
+     *
+     * @example
+     * // Dockerfile: FROM node AS base ... FROM base AS api ... FROM base AS worker
+     * { name: "api", dockerTarget: "api" }   // builds: myapp-api-api-latest
+     * { name: "worker", dockerTarget: "worker" }  // builds: myapp-worker-worker-latest
+     */
+    dockerTarget?: string;
+    /**
+     * Additional inline policies for this service's task role.
+     * Added on top of the default ECS Exec permissions.
+     * Use for service-specific AWS permissions (S3, DynamoDB, SQS, etc.).
+     */
+    taskRoleInlinePolicies?: Record<string, PolicyDocument>;
+    /**
+     * Additional managed policies for this service's task role.
+     * Added on top of the default ECS Exec permissions.
+     */
+    taskRoleManagedPolicies?: IManagedPolicy[];
+    /**
+     * Resources this service needs to connect to (e.g., databases, S3 buckets, SQS queues).
+     * Creates security group rules for IConnectable resources and IAM grants for IAM resources.
+     * Follows least-privilege - only this service gets access, not all services in the cluster.
+     *
+     * Supports:
+     * - IConnectable: Security group resources (RDS, ECS, etc.)
+     * - IStorageConnector: S3 buckets (IAM grants)
+     * - IDynamoDBConnector: DynamoDB tables (IAM grants)
+     * - IQueueConnector: SQS queues (IAM grants)
+     * - ConnectionConfig: Explicit access level configuration
+     *
+     * @example
+     * // Simple connections (default permissions)
+     * connections: [database, bucket, cache, queue]
+     *
+     * @example
+     * // Explicit access levels
+     * connections: [
+     *   database,                              // Security group (RDS)
+     *   { resource: cache, access: "read" },   // Read-only DynamoDB
+     *   { resource: bucket, access: "write" }, // Write-only S3
+     *   { resource: queue, access: "consume" } // Consume-only SQS
+     * ]
+     */
+    connections?: ConnectionSpec[];
+    /**
+     * Cross-app resources reachable via VPC peering. Each entry resolves the
+     * peered app's exposed resource at synth time (SSM `valueForStringParameter`
+     * reads) and injects `${PREFIX}_HOST` + `${PREFIX}_PORT` env vars into every
+     * container in this service's task definition.
+     *
+     * @example
+     * remoteConnections: [
+     *   { peer, resource: "MainDatabase" },
+     *   { peer, resource: "CoreApi", envPrefix: "DATA_PLATFORM_API" }
+     * ]
+     */
+    remoteConnections?: RemoteConnectionSpec[];
+    /**
+     * Capacity provider for this service. REQUIRED.
+     * Each service specifies its own capacity provider.
+     *
+     * @example
+     * // Mixed FARGATE and EC2 services in same cluster
+     * {
+     *   services: [
+     *     { name: "api", capacityProvider: "FARGATE" },
+     *     { name: "worker", capacityProvider: "EC2", ec2Config: { instanceType: "t4g.micro" } }
+     *   ]
+     * }
+     */
+    capacityProvider: EcsCapacityProvider;
+    /**
+     * EC2 capacity configuration for this service.
+     * Only used when service capacityProvider is "EC2".
+     * Services with matching ec2Config share an ASG for efficiency.
+     */
+    ec2Config?: Ec2CapacityConfig;
+    /**
+     * SSM Parameter Store path for secrets.
+     * If not specified, secrets are fetched from /<app>/<cluster>/<service>.
+     * Use this to override the default convention.
+     *
+     * @example
+     * // Override default path
+     * ssmSecretsPath: "/custom/path/to/secrets"
+     */
+    ssmSecretsPath?: string;
+    /**
+     * Per-service alarm configuration.
+     * - undefined: use defaults (CPU, memory, running tasks, 5xx if ALB)
+     * - false: disable alarms for this service
+     * - object: override specific thresholds
+     */
+    alarms?: EcsServiceAlarmThresholds | false;
+}
+/**
+ * ECS compute configuration.
+ * Creates an ECS cluster with one or more services sharing a load balancer.
+ *
+ * @example
+ * // Single service
+ * app.addCompute(ComputeFactory.build("WebApp", {
+ *   type: "ecs",
+ *   cluster: { domain: "app.example.com" },
+ *   services: [{ name: "web", containers: [{ port: 3000 }] }]
+ * }));
+ *
+ * @example
+ * // Multi-service cluster with routing
+ * app.addCompute(ComputeFactory.build("ApiCluster", {
+ *   type: "ecs",
+ *   cluster: { domain: "api.example.com" },
+ *   services: [
+ *     { name: "users", containers: [{ port: 3000 }], routing: { path: "/users/*" } },
+ *     { name: "orders", containers: [{ port: 3001 }], routing: { path: "/orders/*" } }
+ *   ]
+ * }));
+ *
+ * @example
+ * // Internal workers (no ALB)
+ * app.addCompute(ComputeFactory.build("Workers", {
+ *   type: "ecs",
+ *   cluster: { loadBalancer: false },
+ *   services: [{ name: "processor" }, { name: "emailer" }]
+ * }));
+ */
+export interface EcsComputeProps {
+    type: "ecs";
+    vpc?: IVpc;
+    /**
+     * Application name for SSM secrets namespace.
+     * When containers use secrets, the path is derived as: /<appName>/<clusterName>/<serviceName>
+     * Auto-derived from App.getName() if not specified.
+     */
+    appName?: string;
+    /**
+     * Cluster configuration.
+     * Controls the shared ALB for all services in this cluster.
+     * - Omit: ALB created with default settings
+     * - `{ domain: "..." }`: ALB with HTTPS + DNS
+     * - `{ loadBalancer: false }`: No ALB (internal workers)
+     */
+    cluster?: EcsClusterConfig;
+    /**
+     * Services in this cluster.
+     * Each service gets its own task definition, scaling, and target group.
+     * Each service MUST specify its own capacityProvider.
+     * All services share the cluster's ALB (unless disabled).
+     */
+    services: EcsServiceConfig[];
+    /**
+     * ECR repository for all services (default image).
+     * Individual services can override with their own `image` property.
+     */
+    ecrRepository?: Repository | RepositoryImage;
+    /**
+     * Path to Dockerfile for building custom image.
+     * Note: This is metadata for the CLI build process,
+     * not used during CDK synthesis.
+     */
+    dockerfilePath?: string;
+    /**
+     * SNS topic for alarm notifications. Resolved to ITopic and passed to EcsCluster.
+     * Accepts either an ITopic directly or a topic ARN string (resolved internally).
+     */
+    alertsTopic?: ITopic | string;
+    /** Application ID for alarm tagging (used by webhook to map alarms to applications). */
+    applicationId?: string;
+}

package/dist/lib/patterns/aws/computeEcsTypes.js

@@ -0,0 +1,2 @@
+import { ScalingType } from "../../resources/aws/compute/ecs.js";
+export { ScalingType };

package/dist/lib/patterns/aws/domain.js

@@ -6,6 +6,7 @@ import { validateDomainProps } from "./domainValidation.js";
 import { composeApexDomain } from "./apexDomainPattern.js";
 import { composeDelegatedDomain } from "./delegatedDomainPattern.js";
 import { composeExternalRecords } from "./externalRecordsPattern.js";
+import { DEFAULT_COST_ALLOCATION_ENVIRONMENT } from "../../utils/costAllocationTags.js";
 /**
  * User-facing Route53-oriented domain construct. Dispatches on
  * `props.registrar` to one of three per-registrar patterns:
@@ -73,7 +74,7 @@ export class Domain extends Construct {
         const effectiveZone = resolveEffectiveZoneName(props);
         const description = props.description ?? `Fjall-managed domain for ${effectiveZone}`;
         Tags.of(this).add("fjall:description", description);
-        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? "management");
+        Tags.of(this).add("fjall:costAllocation:environment", props.costAllocationEnvironment ?? DEFAULT_COST_ALLOCATION_ENVIRONMENT);
         Tags.of(this).add("fjall:costAllocation:service", "domain");
         Tags.of(this).add("fjall:costAllocation:domain", props.zoneName);
     }
@@ -107,9 +108,7 @@ export class Domain extends Construct {
 }
 function resolveEffectiveZoneName(props) {
     if (props.registrar === "external-delegated") {
-        const delegated = props;
-        return `${delegated.delegatedSubdomain}.${delegated.zoneName}`;
+        return `${props.delegatedSubdomain}.${props.zoneName}`;
     }
-    const narrowed = props;
-    return narrowed.zoneName;
+    return props.zoneName;
 }

package/dist/lib/patterns/aws/index.d.ts

@@ -19,3 +19,5 @@ export * from "./network.js";
 export * from "./cdn.js";
 export * from "./messaging.js";
 export * from "./pattern.js";
+export * from "./vpcPeer.js";
+export * from "./vpcPeerAccepter.js";

package/dist/lib/patterns/aws/index.js

@@ -26,3 +26,5 @@ export * from "./network.js";
 export * from "./cdn.js";
 export * from "./messaging.js";
 export * from "./pattern.js";
+export * from "./vpcPeer.js";
+export * from "./vpcPeerAccepter.js";

package/dist/lib/patterns/aws/interfaces/compute.d.ts

@@ -54,6 +54,12 @@ export interface IEcsCompute extends ICompute, IConnectable {
     getAllServices(): IBaseService[];
     /** Get the security group for the cluster. */
     getSecurityGroup(): ISecurityGroup;
+    /**
+     * Returns the primary ALB listener port if one exists, else `undefined`.
+     * Use as a sensible default when consumers do not specify a port (e.g. 443
+     * for HTTPS, 80 for HTTP); does not indicate protocol.
+     */
+    getPrimaryListenerPort(): number | undefined;
 }
 /**
  * Lambda compute interface.

package/dist/lib/patterns/aws/interfaces/connector.d.ts

@@ -3,4 +3,4 @@
  * Connector types are shared between resources and patterns layers,
  * so they belong in utils per the infrastructure layer boundary rules.
  */
-export { type ConnectorType, type ConnectionAccess, type MessagingAccess, type IConnector, type IStorageConnector, type IDynamoDBConnector, type IQueueConnector, type ISecurityGroupConnector, type AnyConnector, type ConnectionConfig, type ConnectionSpec, CONNECTION_TYPE, type ConnectionType, type ConnectionResult, isConnectionAccess, isMessagingAccess, isConnector, isConnectable, isConnectionConfig, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector } from "../../../utils/connector.js";
+export { type ConnectorType, type ConnectionAccess, type MessagingAccess, type IConnector, type IStorageConnector, type IDynamoDBConnector, type IQueueConnector, type ISecurityGroupConnector, type IRemoteConnector, type AnyConnector, type ConnectionConfig, type ConnectionSpec, CONNECTION_TYPE, type ConnectionType, type ConnectionResult, isConnectionAccess, isMessagingAccess, isConnector, isConnectable, isConnectionConfig, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector, isRemoteConnector } from "../../../utils/connector.js";

package/dist/lib/patterns/aws/interfaces/connector.js

@@ -3,4 +3,4 @@
  * Connector types are shared between resources and patterns layers,
  * so they belong in utils per the infrastructure layer boundary rules.
  */
-export { CONNECTION_TYPE, isConnectionAccess, isMessagingAccess, isConnector, isConnectable, isConnectionConfig, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector } from "../../../utils/connector.js";
+export { CONNECTION_TYPE, isConnectionAccess, isMessagingAccess, isConnector, isConnectable, isConnectionConfig, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector, isRemoteConnector } from "../../../utils/connector.js";

package/dist/lib/patterns/aws/interfaces/index.d.ts

@@ -9,7 +9,8 @@ export { type DatabaseType, type RelationalDatabaseType, type IDatabase, type IR
 export { type MessagingType, type IMessaging, type IQueueMessaging, type ITopicMessaging, type IEventBusMessaging, type AnyMessaging, isMessaging, isQueueMessaging, isTopicMessaging, isEventBusMessaging } from "./messaging.js";
 export { type IStorage, isStorage } from "./storage.js";
 export { type CdnType, type ICdn, type AnyCdn, isCdn } from "./cdn.js";
-export { type ConnectorType, type ConnectionAccess, type MessagingAccess, type IConnector, type IStorageConnector, type IDynamoDBConnector, type IQueueConnector, type ISecurityGroupConnector, type AnyConnector, type ConnectionConfig, type ConnectionSpec, type ConnectionResult, isConnector, isConnectable, isConnectionConfig, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector } from "./connector.js";
+export { type ConnectorType, type ConnectionAccess, type MessagingAccess, type ConnectionType, CONNECTION_TYPE, type IConnector, type IStorageConnector, type IDynamoDBConnector, type IQueueConnector, type ISecurityGroupConnector, type IRemoteConnector, type AnyConnector, type ConnectionConfig, type ConnectionSpec, type ConnectionResult, isConnector, isConnectable, isConnectionConfig, isConnectionAccess, isMessagingAccess, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector, isRemoteConnector } from "./connector.js";
 export { type PatternType, type IPattern, type IPayload, type IPayloadProps, type IPatternProps, type AnyPattern, type PayloadDatabaseConfig, type PayloadComputeConfig, type PayloadCdnConfig, isPayloadPattern, isPattern } from "./pattern.js";
 export { type OrganisationType, type IOrganisation, type IPlatform, type IAccount, type AnyOrganisation, isOrganisation, isPlatform, isAccount, isOrganisationResource } from "./organisation.js";
+export { type IVpcPeer } from "./vpcPeer.js";
 export { type DnsRecordInput, type DelegationInput, type CertificateInput, type DomainApexProps, type DomainDelegatedProps, type IDomainProps } from "./domain.js";

package/dist/lib/patterns/aws/interfaces/index.js

@@ -15,7 +15,7 @@ export { isStorage } from "./storage.js";
 // CDN interfaces
 export { isCdn } from "./cdn.js";
 // Connector interfaces
-export { isConnector, isConnectable, isConnectionConfig, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector } from "./connector.js";
+export { CONNECTION_TYPE, isConnector, isConnectable, isConnectionConfig, isConnectionAccess, isMessagingAccess, isStorageConnector, isDynamoDBConnector, isQueueConnector, isSecurityGroupConnector, isRemoteConnector } from "./connector.js";
 // Pattern interfaces
 export { isPayloadPattern, isPattern } from "./pattern.js";
 // Organisation interfaces

package/dist/lib/patterns/aws/interfaces/vpcPeer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-export from canonical location in lib/utils/.
+ * `IVpcPeer` is shared between `resources/` (SSM lookup helper) and
+ * `patterns/` (consumer-facing `RemoteConnectionSpec`), so it belongs in
+ * `utils/` per the infrastructure layer boundary rules.
+ */
+export { type IVpcPeer } from "../../../utils/vpcPeerInterface.js";

package/dist/lib/patterns/aws/interfaces/vpcPeer.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/patterns/aws/organisation.js

@@ -4,6 +4,7 @@ import { IdentityCenter } from "../../config/aws/identityCenter.js";
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import { OrganisationResource, OrganisationAccount, CostAllocationTagActivator } from "../../resources/aws/organisation/index.js";
 import { stripAndCamelCase } from "../../utils/stripAndCamelCase.js";
+import { CDK_CONTEXT_KEYS } from "../../utils/cdkContext.js";
 import { getConfig } from "../../utils/getConfig.js";
 import { extractAccountNames } from "../../utils/accountsUtils.js";
 /**
@@ -40,7 +41,7 @@ export class Organisation extends Stack {
             this.accountMap[key.toLowerCase()] = value;
         }
         this.accountsConfig = props.accounts;
-        const orgId = this.node.tryGetContext("orgId");
+        const orgId = this.node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);
         const rootId = this.node.tryGetContext("rootId");
         const managementAccountId = this.node.tryGetContext("managementAccountId") ?? this.account;
         if (!orgId || !rootId) {

package/dist/lib/patterns/aws/vpcPeer.d.ts

@@ -0,0 +1,34 @@
+import { type Construct } from "constructs";
+import type App from "../../app.js";
+import { VpcPeeringConnection } from "../../resources/aws/networking/vpcPeeringConnection.js";
+export interface IVpcPeerProps {
+    /** Name of the remote Fjall app to peer with. */
+    peerAppName: string;
+    /** AWS account ID of the remote app. */
+    peerAccountId: string;
+    /** Region of the remote app's VPC. Defaults to the local region. */
+    peerRegion?: string;
+    /** Remote VPC ID. Resolved from SSM (`{prefix}/vpc-id`) if omitted. */
+    peerVpcId?: string;
+    /** Remote VPC CIDR. Resolved from SSM (`{prefix}/vpc-cidr`) if omitted. */
+    peerVpcCidr?: string;
+    /** Accepter role ARN. Resolved from SSM (`{prefix}/peering-role-arn`) if omitted. */
+    peerRoleArn?: string;
+    /**
+     * Accepter route-table IDs. Resolved from the SSM `StringListParameter`
+     * (`{prefix}/route-table-ids`) via `valueForTypedListParameter` if omitted.
+     */
+    peerRouteTableIds?: string[];
+    /** Name of the local VPC to peer from. Defaults to the app's default VPC. */
+    localVpcName?: string;
+    /** Enable DNS resolution across the peering. Defaults to true. */
+    enableDnsResolution?: boolean;
+    /** Cost-allocation override — forwarded to the underlying construct. */
+    costAllocationEnvironment?: string;
+    /** Cost-allocation override — forwarded to the underlying construct. */
+    costAllocationDomain?: string;
+}
+export type VpcPeer = VpcPeeringConnection;
+export declare class VpcPeerFactory {
+    static build(id: string, props: IVpcPeerProps): (app: App, scope: Construct) => VpcPeer;
+}

package/dist/lib/patterns/aws/vpcPeer.js

@@ -0,0 +1,36 @@
+import { StringListParameter, StringParameter } from "aws-cdk-lib/aws-ssm";
+import { buildSsmPrefix, DEFAULT_ORG_ID, resolveOrgId } from "../../utils/cdkContext.js";
+import { VpcPeeringConnection } from "../../resources/aws/networking/vpcPeeringConnection.js";
+export class VpcPeerFactory {
+    static build(id, props) {
+        return (app, scope) => {
+            const localVpc = app.getVpc(props.localVpcName);
+            const orgId = resolveOrgId(app.node, DEFAULT_ORG_ID);
+            const ssmPrefix = buildSsmPrefix(orgId, props.peerAppName);
+            const peerVpcId = props.peerVpcId ??
+                StringParameter.valueForStringParameter(scope, `${ssmPrefix}/vpc-id`);
+            const peerVpcCidr = props.peerVpcCidr ??
+                StringParameter.valueForStringParameter(scope, `${ssmPrefix}/vpc-cidr`);
+            const peerRoleArn = props.peerRoleArn ??
+                StringParameter.valueForStringParameter(scope, `${ssmPrefix}/peering-role-arn`);
+            const peerRouteTableIds = props.peerRouteTableIds ??
+                StringListParameter.valueForTypedListParameter(scope, `${ssmPrefix}/route-table-ids`);
+            const resolvedPeerOrgId = orgId !== DEFAULT_ORG_ID ? orgId : undefined;
+            return new VpcPeeringConnection(scope, id, {
+                localVpc,
+                localVpcCidr: localVpc.vpcCidrBlock,
+                peerVpcId,
+                peerVpcCidr,
+                peerAccountId: props.peerAccountId,
+                peerRegion: props.peerRegion,
+                peerRoleArn,
+                peerRouteTableIds,
+                enableDnsResolution: props.enableDnsResolution,
+                peerAppName: props.peerAppName,
+                peerOrgId: resolvedPeerOrgId,
+                costAllocationEnvironment: props.costAllocationEnvironment,
+                costAllocationDomain: props.costAllocationDomain
+            });
+        };
+    }
+}

package/dist/lib/patterns/aws/vpcPeerAccepter.d.ts

@@ -0,0 +1,29 @@
+import { type Construct } from "constructs";
+import type App from "../../app.js";
+import { VpcPeeringAccepterRole } from "../../resources/aws/networking/vpcPeeringAccepterRole.js";
+import { type IRelationalDatabase } from "./interfaces/database.js";
+import { type IEcsCompute } from "./interfaces/compute.js";
+export type ExposedResource = {
+    resource: IRelationalDatabase;
+    name: string;
+    allowedFromCidrs: string[];
+    access?: "read" | "write" | "readWrite";
+} | {
+    resource: IEcsCompute;
+    serviceName: string;
+    name: string;
+    allowedFromCidrs: string[];
+    port?: number;
+};
+export interface IVpcPeerAccepterProps {
+    requesterAccountIds: string[];
+    localVpcName?: string;
+    publishToSsm?: boolean;
+    exposedResources?: ExposedResource[];
+    costAllocationEnvironment?: string;
+    costAllocationDomain?: string;
+}
+export type VpcPeerAccepter = VpcPeeringAccepterRole;
+export declare class VpcPeerAccepterFactory {
+    static build(id: string, props: IVpcPeerAccepterProps): (app: App, scope: Construct) => VpcPeerAccepter;
+}