@composurecdk/ec2 0.8.4 → 0.8.6

package/dist/esm/interface-endpoint-builder.js

@@ -0,0 +1,123 @@
+import { InterfaceVpcEndpoint, } from "aws-cdk-lib/aws-ec2";
+import { COPY_STATE, resolve } from "@composurecdk/core";
+import { taggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createSecurityGroupBuilder } from "./security-group-builder.js";
+import { INTERFACE_ENDPOINT_DEFAULTS } from "./interface-endpoint-defaults.js";
+import { createInterfaceEndpointAlarms } from "./interface-endpoint-alarms.js";
+class InterfaceEndpointBuilder {
+    props = {};
+    #access = [];
+    #customAlarms = [];
+    #vpc;
+    #securityGroups;
+    /**
+     * Sets the VPC the endpoint is created in. Accepts a concrete {@link IVpc}
+     * or a {@link Ref} to a sibling {@link IVpcBuilder}.
+     */
+    vpc(vpc) {
+        this.#vpc = vpc;
+        return this;
+    }
+    /**
+     * Bring-your-own security groups. Each entry is a {@link Resolvable}, so it
+     * can be a concrete {@link ISecurityGroup} or a {@link Ref} to a sibling
+     * `SecurityGroupBuilder` — giving you full ingress/egress/port control. When
+     * set, the builder creates no security group of its own and
+     * {@link InterfaceEndpointBuilderResult.securityGroup} is `undefined`.
+     *
+     * Mutually exclusive with {@link allowDefaultPortFrom}.
+     */
+    securityGroups(securityGroups) {
+        this.#securityGroups = securityGroups;
+        return this;
+    }
+    /**
+     * Managed-SG shortcut: wires `peer` to the auto-created security group via
+     * CDK's `endpoint.connections.allowDefaultPortFrom(peer)` — opening ingress
+     * on the managed SG from `peer`'s SG **and** egress from `peer`'s SG to the
+     * managed SG, on the service's default port (443 for AWS services).
+     *
+     * Because this delegates to CDK connections, `peer` must be an
+     * {@link IConnectable} (e.g. a `SecurityGroup` or `Instance`), not a raw
+     * `IPeer` (e.g. `Peer.ipv4(...)`). For CIDR-based rules use BYO mode with
+     * an explicit `addIngressRule` on your own {@link SecurityGroupBuilder}.
+     *
+     * Mutually exclusive with {@link securityGroups}.
+     */
+    allowDefaultPortFrom(peer, description) {
+        this.#access.push({ peer, description });
+        return this;
+    }
+    /**
+     * Adds a custom CloudWatch alarm alongside the recommended ones. The
+     * callback receives an {@link AlarmDefinitionBuilder} typed to the
+     * `InterfaceVpcEndpoint` construct, giving access to the endpoint at
+     * build time for metric dimension wiring.
+     */
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#vpc = this.#vpc;
+        target.#securityGroups = this.#securityGroups ? [...this.#securityGroups] : undefined;
+        target.#access.push(...this.#access);
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id, context) {
+        const resolvedVpc = this.#vpc ? resolve(this.#vpc, context) : undefined;
+        if (!resolvedVpc) {
+            throw new Error(`InterfaceEndpointBuilder "${id}" requires a VPC. Call .vpc() with an IVpc or a Ref to one.`);
+        }
+        const { recommendedAlarms: alarmConfig, service, ...endpointProps } = this.props;
+        if (service === undefined) {
+            throw new Error(`InterfaceEndpointBuilder "${id}" requires a service. ` +
+                "Call .service() with an InterfaceVpcEndpointAwsService or a custom IInterfaceVpcEndpointService.");
+        }
+        const byo = this.#securityGroups;
+        if (byo !== undefined && this.#access.length > 0) {
+            throw new Error(`InterfaceEndpointBuilder "${id}": .allowDefaultPortFrom() applies only to the ` +
+                "auto-created security group and cannot be combined with .securityGroups() — " +
+                "add the ingress rule to your own SecurityGroupBuilder instead.");
+        }
+        let managedSecurityGroup;
+        let securityGroups;
+        if (byo !== undefined) {
+            securityGroups = byo.map((sg) => resolve(sg, context));
+        }
+        else {
+            managedSecurityGroup = createSecurityGroupBuilder()
+                .vpc(resolvedVpc)
+                .description(`Interface endpoint ${id}`)
+                .build(scope, `${id}Sg`).securityGroup;
+            securityGroups = [managedSecurityGroup];
+        }
+        const endpoint = new InterfaceVpcEndpoint(scope, id, {
+            ...INTERFACE_ENDPOINT_DEFAULTS,
+            ...endpointProps,
+            service,
+            vpc: resolvedVpc,
+            securityGroups,
+            // Always explicit: `open: true` would silently add a VPC-wide :443 rule.
+            open: false,
+        });
+        for (const rule of this.#access) {
+            endpoint.connections.allowDefaultPortFrom(resolve(rule.peer, context), rule.description);
+        }
+        const alarms = createInterfaceEndpointAlarms(scope, id, endpoint, alarmConfig, this.#customAlarms);
+        return { endpoint, securityGroup: managedSecurityGroup, alarms };
+    }
+}
+/**
+ * Creates a new {@link IInterfaceEndpointBuilder} for a single VPC interface
+ * endpoint. The returned builder exposes every
+ * {@link InterfaceEndpointBuilderProps} property as a fluent setter/getter,
+ * plus `.vpc()`, `.securityGroups()` (BYO), and `.allowDefaultPortFrom()`
+ * (managed-SG shortcut).
+ */
+export function createInterfaceEndpointBuilder() {
+    return taggedBuilder(InterfaceEndpointBuilder);
+}
+//# sourceMappingURL=interface-endpoint-builder.js.map

package/dist/esm/interface-endpoint-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface-endpoint-builder.js","sourceRoot":"","sources":["../../src/interface-endpoint-builder.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,GAMrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAkB,OAAO,EAAmB,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAuB,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAE/E,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AA2F/E,MAAM,wBAAwB;IAC5B,KAAK,GAA2C,EAAE,CAAC;IAC1C,OAAO,GAAiB,EAAE,CAAC;IAC3B,aAAa,GAAmD,EAAE,CAAC;IAC5E,IAAI,CAAoB;IACxB,eAAe,CAAgC;IAE/C;;;OAGG;IACH,GAAG,CAAC,GAAqB;QACvB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,cAA4C;QACzD,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,IAA8B,EAAE,WAAoB;QACvE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CACN,GAAW,EACX,SAEiD;QAEjD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAuB,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAgC;QAC3C,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,MAAM,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACtF,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CACH,KAAiB,EACjB,EAAU,EACV,OAAgC;QAEhC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,6BAA6B,EAAE,6DAA6D,CAC7F,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACjF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,6BAA6B,EAAE,wBAAwB;gBACrD,kGAAkG,CACrG,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC;QACjC,IAAI,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CACb,6BAA6B,EAAE,iDAAiD;gBAC9E,8EAA8E;gBAC9E,gEAAgE,CACnE,CAAC;QACJ,CAAC;QAED,IAAI,oBAA+C,CAAC;QACpD,IAAI,cAAgC,CAAC;QACrC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,cAAc,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QACzD,CAAC;aAAM,CAAC;YACN,oBAAoB,GAAG,0BAA0B,EAAE;iBAChD,GAAG,CAAC,WAAW,CAAC;iBAChB,WAAW,CAAC,sBAAsB,EAAE,EAAE,CAAC;iBACvC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,aAAa,CAAC;YACzC,cAAc,GAAG,CAAC,oBAAoB,CAAC,CAAC;QAC1C,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC,KAAK,EAAE,EAAE,EAAE;YACnD,GAAG,2BAA2B;YAC9B,GAAG,aAAa;YAChB,OAAO;YACP,GAAG,EAAE,WAAW;YAChB,cAAc;YACd,yEAAyE;YACzE,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;QAEH,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAChC,QAAQ,CAAC,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3F,CAAC;QAED,MAAM,MAAM,GAAG,6BAA6B,CAC1C,KAAK,EACL,EAAE,EACF,QAAQ,EACR,WAAW,EACX,IAAI,CAAC,aAAa,CACnB,CAAC;QAEF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,EAAE,CAAC;IACnE,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B;IAC5C,OAAO,aAAa,CAClB,wBAAwB,CACzB,CAAC;AACJ,CAAC"}

package/dist/esm/interface-endpoint-defaults.d.ts

@@ -0,0 +1,14 @@
+import type { InterfaceVpcEndpointProps } from "aws-cdk-lib/aws-ec2";
+/**
+ * Secure, AWS-recommended defaults applied to every interface endpoint built
+ * with {@link createInterfaceEndpointBuilder}. Each property can be
+ * individually overridden via the builder's fluent API.
+ *
+ * Note `open` is intentionally *not* here: the builder always sets it to
+ * `false` (see the builder's `build()`). Allowing it through would silently
+ * add a VPC-wide rule to the managed security group behind the caller's back;
+ * ingress is always explicit — via `.allowDefaultPortFrom()` (managed SG) or
+ * the BYO `SecurityGroupBuilder`.
+ */
+export declare const INTERFACE_ENDPOINT_DEFAULTS: Partial<InterfaceVpcEndpointProps>;
+//# sourceMappingURL=interface-endpoint-defaults.d.ts.map

package/dist/esm/interface-endpoint-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface-endpoint-defaults.d.ts","sourceRoot":"","sources":["../../src/interface-endpoint-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAErE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,EAAE,OAAO,CAAC,yBAAyB,CAW1E,CAAC"}

package/dist/esm/interface-endpoint-defaults.js

@@ -0,0 +1,24 @@
+/**
+ * Secure, AWS-recommended defaults applied to every interface endpoint built
+ * with {@link createInterfaceEndpointBuilder}. Each property can be
+ * individually overridden via the builder's fluent API.
+ *
+ * Note `open` is intentionally *not* here: the builder always sets it to
+ * `false` (see the builder's `build()`). Allowing it through would silently
+ * add a VPC-wide rule to the managed security group behind the caller's back;
+ * ingress is always explicit — via `.allowDefaultPortFrom()` (managed SG) or
+ * the BYO `SecurityGroupBuilder`.
+ */
+export const INTERFACE_ENDPOINT_DEFAULTS = {
+    /**
+     * Private DNS enables `<service>.<region>.amazonaws.com` to resolve to the
+     * endpoint ENIs instead of the public service IP addresses, keeping traffic
+     * on the AWS network without requiring application-level changes. Disabled
+     * by default in raw CDK; always on here because every AWS-service use case
+     * requires it for transparent private access.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_network_protection_private_connectivity.html
+     */
+    privateDnsEnabled: true,
+};
+//# sourceMappingURL=interface-endpoint-defaults.js.map

package/dist/esm/interface-endpoint-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface-endpoint-defaults.js","sourceRoot":"","sources":["../../src/interface-endpoint-defaults.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAuC;IAC7E;;;;;;;;OAQG;IACH,iBAAiB,EAAE,IAAI;CACxB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/ec2",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Composable EC2 instance and VPC builders with well-architected defaults",
   "repository": {
     "type": "git",
@@ -20,7 +20,18 @@
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest"
   },
-  "keywords": [],
+  "keywords": [
+    "aws",
+    "cdk",
+    "aws-cdk",
+    "infrastructure-as-code",
+    "iac",
+    "composurecdk",
+    "ec2",
+    "vpc",
+    "networking",
+    "compute"
+  ],
   "author": "Jason Duffett (https://github.com/laazyj)",
   "license": "MIT",
   "publishConfig": {
@@ -45,11 +56,11 @@
     "constructs": "^10.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
-    "aws-cdk-lib": "^2.257.0",
+    "@types/node": "^25.9.3",
+    "aws-cdk-lib": "^2.258.1",
     "constructs": "^10.6.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "exports": {
     "./package.json": "./package.json",