alchemy 0.61.0 → 0.62.0

package/src/aws/credentials.ts

@@ -1,6 +1,167 @@
-import type { Secret } from "../secret.ts";
+import { alchemy } from "../alchemy.ts";
+import { isSecret } from "../secret.ts";
+import type { AwsClientProps } from "./client-props.ts";
 
-export interface AwsCredentials {
-  accessKeyId: Secret;
-  secretAccessKey: Secret;
+/**
+ * Validate AWS client properties to ensure they are strings.
+ * This follows the same pattern as Cloudflare credential validation.
+ */
+function validateAwsClientProps(props: AwsClientProps, context: string): void {
+  const validKeys = [
+    "accessKeyId",
+    "secretAccessKey",
+    "sessionToken",
+    "region",
+    "profile",
+    "roleArn",
+    "externalId",
+    "roleSessionName",
+  ];
+
+  for (const [key, value] of Object.entries(props)) {
+    if (!validKeys.includes(key)) {
+      continue; // Ignore unknown properties
+    }
+
+    if (value !== undefined && typeof value !== "string" && !isSecret(value)) {
+      throw new Error(
+        `Invalid AWS configuration in ${context}: Property '${key}' must be a string or Secret, got ${typeof value}. ` +
+          "Please ensure all AWS credential properties are strings or Secret objects.",
+      );
+    }
+  }
+}
+
+/**
+ * Get global AWS configuration from environment variables.
+ * This provides the base layer of AWS credential configuration.
+ */
+export function getGlobalAwsConfig(): AwsClientProps {
+  return {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID
+      ? alchemy.secret(process.env.AWS_ACCESS_KEY_ID)
+      : undefined,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+      ? alchemy.secret(process.env.AWS_SECRET_ACCESS_KEY)
+      : undefined,
+    sessionToken: process.env.AWS_SESSION_TOKEN
+      ? alchemy.secret(process.env.AWS_SESSION_TOKEN)
+      : undefined,
+    region: process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION,
+    profile: process.env.AWS_PROFILE,
+    roleArn: process.env.AWS_ROLE_ARN,
+    externalId: process.env.AWS_EXTERNAL_ID,
+    roleSessionName: process.env.AWS_ROLE_SESSION_NAME,
+  };
+}
+
+/**
+ * Resolve AWS credentials using three-tier resolution: global → scope → resource.
+ *
+ * This function implements a comprehensive credential resolution system that allows
+ * for flexible AWS credential management across different levels of your application.
+ * It enables multi-account and multi-region deployments by providing a consistent
+ * way to override credentials at different scopes.
+ *
+ * The resolution follows this precedence order:
+ * 1. Resource-level credentials (highest priority)
+ * 2. Scope-level credentials (medium priority)
+ * 3. Global environment variables (lowest priority)
+ *
+ * Supported credential properties include:
+ * - `region`: AWS region (e.g., 'us-west-2', 'eu-central-1')
+ * - `profile`: AWS profile name from credentials file
+ * - `accessKeyId`: AWS access key ID
+ * - `secretAccessKey`: AWS secret access key
+ * - `sessionToken`: AWS session token for temporary credentials
+ * - `roleArn`: AWS role ARN to assume
+ * - `roleSessionName`: Session name when assuming a role
+ * - `externalId`: External ID when assuming a role
+ *
+ * @param resourceProps - Resource-level AWS credential properties (optional)
+ * @returns Resolved AWS client properties with validation
+ *
+ * @throws {Error} When scope contains invalid AWS configuration
+ * @throws {Error} When resource properties contain invalid AWS configuration
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with resource-level credentials
+ * const credentials = resolveAwsCredentials({
+ *   region: "us-west-2",
+ *   profile: "production"
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage with scope-level credentials
+ * await alchemy.run("my-app", {
+ *   aws: {
+ *     region: "eu-west-1",
+ *     profile: "staging"
+ *   }
+ * }, async () => {
+ *   // Resources created here will use the scope credentials by default
+ *   const vpc = await Vpc("main-vpc", {
+ *     cidrBlock: "10.0.0.0/16"
+ *   });
+ *
+ *   // Resources can override scope credentials
+ *   const crossRegionSubnet = await Subnet("cross-region-subnet", {
+ *     vpc,
+ *     cidrBlock: "10.0.1.0/24",
+ *     region: "us-east-1" // Override scope region
+ *   });
+ * });
+ * ```
+ */
+export async function resolveAwsCredentials(
+  resourceProps?: AwsClientProps,
+): Promise<AwsClientProps> {
+  // 1. Start with global environment variables (lowest priority)
+  const globalConfig = getGlobalAwsConfig();
+
+  // 2. Layer in scope-level credentials (medium priority)
+  let scopeConfig: AwsClientProps = {};
+  try {
+    // Import Scope dynamically to avoid circular dependency
+    const { Scope } = await import("../scope.ts");
+    const currentScope = Scope.getScope();
+    if (currentScope?.providerCredentials?.aws) {
+      scopeConfig = currentScope.providerCredentials.aws;
+
+      // Validate scope-level credentials if provided
+      validateAwsClientProps(scopeConfig, "scope");
+    }
+  } catch (error) {
+    // If we can't access scope (e.g., not running in scope context), just continue
+    // with empty scope config unless it's a validation error
+    if (
+      error instanceof Error &&
+      error.message.includes("Invalid AWS configuration")
+    ) {
+      throw error;
+    }
+  }
+
+  // 3. Layer in resource-level credentials (highest priority)
+  const resourceConfig = resourceProps || {};
+
+  // Validate resource-level credentials if provided
+  if (resourceProps && Object.keys(resourceProps).length > 0) {
+    validateAwsClientProps(resourceProps, "resource properties");
+  }
+
+  // Merge configurations with proper precedence (later properties override earlier ones)
+  const resolvedConfig = {
+    ...globalConfig,
+    ...scopeConfig,
+    ...resourceConfig,
+  };
+
+  // Filter out undefined values from the final result
+  return Object.fromEntries(
+    Object.entries(resolvedConfig).filter(([_, value]) => value !== undefined),
+  ) as AwsClientProps;
 }

package/src/aws/ec2/internet-gateway-attachment.ts

@@ -8,6 +8,7 @@ import {
   type TimeoutConfig,
   waitForResourceState,
 } from "../../util/timeout.ts";
+import type { AwsClientProps } from "../client-props.ts";
 import type { InternetGateway } from "./internet-gateway.ts";
 import { callEC2Api, createEC2Client } from "./utils.ts";
 import type { Vpc } from "./vpc.ts";
@@ -15,7 +16,7 @@ import type { Vpc } from "./vpc.ts";
 /**
  * Properties for creating or updating an Internet Gateway Attachment
  */
-export interface InternetGatewayAttachmentProps {
+export interface InternetGatewayAttachmentProps extends AwsClientProps {
   /**
    * The Internet Gateway to attach
    */
@@ -67,6 +68,9 @@ export interface InternetGatewayAttachment
  * allowing traffic to flow between the VPC and the internet when combined with proper
  * routing configuration.
  *
+ * Supports AWS credential overrides at the resource level, allowing you to deploy Internet Gateway Attachments
+ * to different AWS accounts or regions than the default scope configuration.
+ *
  * @example
  * // Basic Internet Gateway attachment for internet connectivity
  * const vpc = await Vpc("main-vpc", {
@@ -81,6 +85,36 @@ export interface InternetGatewayAttachment
  * });
  *
  * @example
+ * // Internet Gateway Attachment with AWS credential overrides
+ * const crossAccountAttachment = await InternetGatewayAttachment("cross-account-attachment", {
+ *   internetGateway: igw,
+ *   vpc: vpc,
+ *   // Override AWS credentials for this specific resource
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ * });
+ *
+ * @example
+ * // Internet Gateway Attachment in different region with role assumption
+ * const multiRegionAttachment = await InternetGatewayAttachment("multi-region-attachment", {
+ *   internetGateway: euIgw,
+ *   vpc: euVpc,
+ *   region: "eu-west-1",
+ *   roleArn: "arn:aws:iam::123456789012:role/CrossRegionRole",
+ *   roleSessionName: "igw-attachment-deployment",
+ * });
+ *
+ * @example
+ * // Internet Gateway Attachment with explicit credentials
+ * const explicitCredsAttachment = await InternetGatewayAttachment("explicit-creds-attachment", {
+ *   internetGateway: testIgw,
+ *   vpc: testVpc,
+ *   accessKeyId: alchemy.secret("AKIAIOSFODNN7EXAMPLE"),
+ *   secretAccessKey: alchemy.secret("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
+ *   region: "us-west-2",
+ * });
+ *
+ * @example
  * // Internet Gateway attachment with custom timeout configuration
  * // for environments with slower AWS API responses
  * const attachment = await InternetGatewayAttachment("slow-env-attachment", {
@@ -109,7 +143,7 @@ export interface InternetGatewayAttachment
  *
  * // Create public subnet and route table for internet access
  * const publicSubnet = await Subnet("public-subnet", {
- *   vpc,
+ *   vpc: vpc,
  *   cidrBlock: "10.0.1.0/24",
  *   availabilityZone: "us-east-1a"
  * });
@@ -121,7 +155,27 @@ export interface InternetGatewayAttachment
  * const internetRoute = await Route("internet-route", {
  *   routeTable: publicRouteTable,
  *   destinationCidrBlock: "0.0.0.0/0",
- *   gateway: igw
+ *   target: { internetGateway: igw }
+ * });
+ *
+ * @example
+ * // Multi-account deployment with scope-level and resource-level overrides
+ * await alchemy.run("production", {
+ *   aws: { region: "us-west-2", profile: "main-account" }
+ * }, async () => {
+ *   // This Internet Gateway Attachment uses scope credentials (main-account, us-west-2)
+ *   const mainAttachment = await InternetGatewayAttachment("main-attachment", {
+ *     internetGateway: mainIgw,
+ *     vpc: mainVpc
+ *   });
+ *
+ *   // This Internet Gateway Attachment overrides to use different account
+ *   const crossAccountAttachment = await InternetGatewayAttachment("cross-account-attachment", {
+ *     internetGateway: crossIgw,
+ *     vpc: crossVpc,
+ *     profile: "secondary-account",
+ *     region: "us-east-1", // Also override region
+ *   });
  * });
  */
 export const InternetGatewayAttachment = Resource(
@@ -131,7 +185,8 @@ export const InternetGatewayAttachment = Resource(
     _id: string,
     props: InternetGatewayAttachmentProps,
   ): Promise<InternetGatewayAttachment> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const timeoutConfig = mergeTimeoutConfig(
       INTERNET_GATEWAY_ATTACHMENT_TIMEOUT,
       props.timeout,

package/src/aws/ec2/internet-gateway.ts

@@ -9,12 +9,13 @@ import {
   type TimeoutConfig,
   waitForResourceState,
 } from "../../util/timeout.ts";
+import type { AwsClientProps } from "../client-props.ts";
 import { callEC2Api, createEC2Client } from "./utils.ts";
 
 /**
  * Properties for creating or updating an Internet Gateway
  */
-export interface InternetGatewayProps {
+export interface InternetGatewayProps extends AwsClientProps {
   /**
    * Tags to apply to the Internet Gateway
    */
@@ -145,12 +146,15 @@ async function waitForInternetGatewayDeleted(
  * 1. Provide a target in your VPC route tables for internet-routable traffic
  * 2. Perform network address translation (NAT) for instances with public IPv4 addresses
  *
+ * Supports AWS credential overrides at the resource level, allowing you to deploy Internet Gateways
+ * to different AWS accounts or regions than the default scope configuration.
+ *
  * @example
  * ```typescript
  * // Create a basic Internet Gateway
- * const igw = new InternetGateway({
+ * const igw = await InternetGateway("main-igw", {
  *   tags: {
- *     Name: "my-internet-gateway",
+ *     Name: "main-internet-gateway",
  *     Environment: "production"
  *   }
  * });
@@ -158,59 +162,49 @@ async function waitForInternetGatewayDeleted(
  *
  * @example
  * ```typescript
- * // Create Internet Gateway with custom timeout configuration
- * const igw = new InternetGateway({
- *   tags: { Name: "custom-igw" },
- *   timeoutConfig: {
- *     maxAttempts: 30,
- *     delayMs: 1000
+ * // Create Internet Gateway with AWS credential overrides
+ * const crossAccountIgw = await InternetGateway("cross-account-igw", {
+ *   // Override AWS credentials for this specific resource
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ *   tags: {
+ *     Name: "cross-account-internet-gateway",
+ *     Environment: "production"
  *   }
  * });
  * ```
  *
  * @example
  * ```typescript
- * // Create Internet Gateway and attach to VPC
- * const vpc = new VPC({ cidrBlock: "10.0.0.0/16" });
- * const igw = new InternetGateway({ tags: { Name: "vpc-igw" } });
- * const attachment = new InternetGatewayAttachment({
- *   internetGatewayId: igw.internetGatewayId,
- *   vpcId: vpc.vpcId
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Access Internet Gateway properties
- * const igw = new InternetGateway({ tags: { Name: "example-igw" } });
- * logger.log(`Internet Gateway ID: ${igw.internetGatewayId}`);
- * logger.log(`State: ${igw.state}`);
- * ```
- *
- * Creates and manages Internet Gateways that provide internet access to VPCs.
- * Note: Use InternetGatewayAttachment to attach the gateway to a VPC.
- *
- * @example
- * // Create a basic Internet Gateway
- * const igw = await InternetGateway("main-igw", {
+ * // Create Internet Gateway in different region with role assumption
+ * const multiRegionIgw = await InternetGateway("multi-region-igw", {
+ *   region: "eu-west-1",
+ *   roleArn: "arn:aws:iam::123456789012:role/CrossRegionRole",
+ *   roleSessionName: "internet-gateway-deployment",
  *   tags: {
- *     Name: "main-internet-gateway",
- *     Environment: "production"
+ *     Name: "eu-internet-gateway",
+ *     Region: "europe"
  *   }
  * });
+ * ```
  *
  * @example
- * // Create an Internet Gateway for development environment
- * const devIgw = await InternetGateway("dev-igw", {
+ * ```typescript
+ * // Create Internet Gateway with explicit credentials
+ * const explicitCredsIgw = await InternetGateway("explicit-creds-igw", {
+ *   accessKeyId: alchemy.secret("AKIAIOSFODNN7EXAMPLE"),
+ *   secretAccessKey: alchemy.secret("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
+ *   region: "us-west-2",
  *   tags: {
- *     Name: "dev-internet-gateway",
- *     Environment: "development",
- *     Team: "backend"
+ *     Name: "explicit-credentials-igw",
+ *     Purpose: "testing"
  *   }
  * });
+ * ```
  *
  * @example
- * // Create an Internet Gateway with custom timeout configuration
+ * ```typescript
+ * // Create Internet Gateway with custom timeout configuration
  * const customIgw = await InternetGateway("custom-igw", {
  *   timeout: {
  *     maxAttempts: 90,
@@ -221,6 +215,40 @@ async function waitForInternetGatewayDeleted(
  *     Purpose: "high-availability"
  *   }
  * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create Internet Gateway and attach to VPC
+ * const vpc = await VPC("main-vpc", { cidrBlock: "10.0.0.0/16" });
+ * const igw = await InternetGateway("vpc-igw", {
+ *   tags: { Name: "vpc-internet-gateway" }
+ * });
+ * const attachment = await InternetGatewayAttachment("igw-attachment", {
+ *   internetGatewayId: igw.internetGatewayId,
+ *   vpcId: vpc.vpcId
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multi-account deployment with scope-level and resource-level overrides
+ * await alchemy.run("production", {
+ *   aws: { region: "us-west-2", profile: "main-account" }
+ * }, async () => {
+ *   // This IGW uses scope credentials (main-account, us-west-2)
+ *   const mainIgw = await InternetGateway("main-igw", {
+ *     tags: { Name: "main-account-igw" }
+ *   });
+ *
+ *   // This IGW overrides to use different account
+ *   const crossAccountIgw = await InternetGateway("cross-account-igw", {
+ *     profile: "secondary-account",
+ *     region: "us-east-1", // Also override region
+ *     tags: { Name: "secondary-account-igw" }
+ *   });
+ * });
+ * ```
  */
 export const InternetGateway = Resource(
   "aws::InternetGateway",
@@ -229,7 +257,8 @@ export const InternetGateway = Resource(
     _id: string,
     props: InternetGatewayProps,
   ): Promise<InternetGateway> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const timeoutConfig = mergeTimeoutConfig(
       INTERNET_GATEWAY_TIMEOUT,
       props.timeout,