alchemy 0.60.2 → 0.62.0

package/src/aws/ec2/route.ts

@@ -9,6 +9,7 @@ import {
   type TimeoutConfig,
   waitForResourceState,
 } from "../../util/timeout.ts";
+import type { AwsClientProps } from "../client-props.ts";
 import { retry } from "../retry.ts";
 import type { InternetGateway } from "./internet-gateway.ts";
 import type { NatGateway } from "./nat-gateway.ts";
@@ -18,7 +19,7 @@ import { callEC2Api, createEC2Client } from "./utils.ts";
 /**
  * Properties for creating or updating a Route
  */
-export interface RouteProps {
+export interface RouteProps extends AwsClientProps {
   /**
    * The route table to add the route to
    */
@@ -74,6 +75,9 @@ export interface Route extends Resource<"aws::Route">, RouteProps {
  * Creates and manages individual routes within route tables, directing traffic
  * to various targets like Internet Gateways, NAT Gateways, or instances.
  *
+ * Supports AWS credential overrides at the resource level, allowing you to deploy Routes
+ * to different AWS accounts or regions than the default scope configuration.
+ *
  * @example
  * // Create a default route to Internet Gateway
  * const publicRoute = await Route("public-default-route", {
@@ -91,6 +95,39 @@ export interface Route extends Resource<"aws::Route">, RouteProps {
  * });
  *
  * @example
+ * // Create Route with AWS credential overrides
+ * const crossAccountRoute = await Route("cross-account-route", {
+ *   routeTable: mainRouteTable,
+ *   destinationCidrBlock: "0.0.0.0/0",
+ *   target: { internetGateway: mainIgw },
+ *   // Override AWS credentials for this specific resource
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ * });
+ *
+ * @example
+ * // Create Route in different region with role assumption
+ * const multiRegionRoute = await Route("multi-region-route", {
+ *   routeTable: euRouteTable,
+ *   destinationCidrBlock: "0.0.0.0/0",
+ *   target: { internetGateway: euIgw },
+ *   region: "eu-west-1",
+ *   roleArn: "arn:aws:iam::123456789012:role/CrossRegionRole",
+ *   roleSessionName: "route-deployment",
+ * });
+ *
+ * @example
+ * // Create Route with explicit credentials
+ * const explicitCredsRoute = await Route("explicit-creds-route", {
+ *   routeTable: testRouteTable,
+ *   destinationCidrBlock: "0.0.0.0/0",
+ *   target: { internetGateway: testIgw },
+ *   accessKeyId: alchemy.secret("AKIAIOSFODNN7EXAMPLE"),
+ *   secretAccessKey: alchemy.secret("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
+ *   region: "us-west-2",
+ * });
+ *
+ * @example
  * // Create a route to a specific instance
  * const instanceRoute = await Route("instance-route", {
  *   routeTable: "rtb-12345678",
@@ -133,6 +170,28 @@ export interface Route extends Resource<"aws::Route">, RouteProps {
  *     delayMs: 2000
  *   }
  * });
+ *
+ * @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 Route uses scope credentials (main-account, us-west-2)
+ *   const mainRoute = await Route("main-route", {
+ *     routeTable: mainRouteTable,
+ *     destinationCidrBlock: "0.0.0.0/0",
+ *     target: { internetGateway: mainIgw }
+ *   });
+ *
+ *   // This Route overrides to use different account
+ *   const crossAccountRoute = await Route("cross-account-route", {
+ *     routeTable: crossRouteTable,
+ *     destinationCidrBlock: "0.0.0.0/0",
+ *     target: { internetGateway: crossIgw },
+ *     profile: "secondary-account",
+ *     region: "us-east-1", // Also override region
+ *   });
+ * });
  */
 export const Route = Resource(
   "aws::Route",
@@ -141,7 +200,8 @@ export const Route = Resource(
     _id: string,
     props: RouteProps,
   ): Promise<Route> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const _timeoutConfig = mergeTimeoutConfig(ROUTE_TIMEOUT, props.timeout);
     const routeTableId =
       typeof props.routeTable === "string"

package/src/aws/ec2/security-group.ts

@@ -8,6 +8,7 @@ import {
   type TimeoutConfig,
   waitForResourceState,
 } from "../../util/timeout.ts";
+import type { AwsClientProps } from "../client-props.ts";
 import { callEC2Api, createEC2Client } from "./utils.ts";
 import type { Vpc } from "./vpc.ts";
 
@@ -22,7 +23,7 @@ export const SECURITY_GROUP_TIMEOUT: TimeoutConfig = {
 /**
  * Properties for creating or updating a Security Group
  */
-export interface SecurityGroupProps {
+export interface SecurityGroupProps extends AwsClientProps {
   /**
    * The VPC to create the security group in.
    */
@@ -79,8 +80,12 @@ export interface SecurityGroup
  * instances and other AWS resources. Rules are managed separately using the
  * `SecurityGroupRule` resource.
  *
+ * Supports AWS credential overrides at the resource level, allowing you to deploy Security Groups
+ * to different AWS accounts or regions than the default scope configuration.
+ *
  * @example
- * // Create a web server security group
+ * ```typescript
+ * // Create a basic web server security group
  * const webSecurityGroup = await SecurityGroup("web-sg", {
  *   vpc: mainVpc,
  *   groupName: "web-server-sg",
@@ -90,11 +95,72 @@ export interface SecurityGroup
  *     Environment: "production"
  *   }
  * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create Security Group with AWS credential overrides
+ * const crossAccountSg = await SecurityGroup("cross-account-sg", {
+ *   vpc: mainVpc,
+ *   groupName: "cross-account-security-group",
+ *   description: "Security group in different account",
+ *   // Override AWS credentials for this specific resource
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ *   tags: {
+ *     Name: "cross-account-sg",
+ *     Environment: "production"
+ *   }
+ * });
+ * ```
  *
  * @example
+ * ```typescript
+ * // Create Security Group in different region with role assumption
+ * const multiRegionSg = await SecurityGroup("multi-region-sg", {
+ *   vpc: euVpc,
+ *   groupName: "eu-security-group",
+ *   description: "Security group in EU region",
+ *   region: "eu-west-1",
+ *   roleArn: "arn:aws:iam::123456789012:role/CrossRegionRole",
+ *   roleSessionName: "security-group-deployment",
+ *   tags: {
+ *     Name: "eu-security-group",
+ *     Region: "europe"
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create Security Group with explicit credentials
+ * const explicitCredsSg = await SecurityGroup("explicit-creds-sg", {
+ *   vpc: testVpc,
+ *   groupName: "test-security-group",
+ *   description: "Security group with explicit credentials",
+ *   accessKeyId: alchemy.secret("AKIAIOSFODNN7EXAMPLE"),
+ *   secretAccessKey: alchemy.secret("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
+ *   region: "us-west-2",
+ *   tags: {
+ *     Name: "explicit-credentials-sg",
+ *     Purpose: "testing"
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create Security Group with rules (rules managed separately)
+ * const webSg = await SecurityGroup("web-sg", {
+ *   vpc: mainVpc,
+ *   groupName: "web-server-sg",
+ *   description: "Security group for web servers",
+ *   tags: { Name: "web-server-security-group" }
+ * });
+ *
  * // Separately, define a rule to allow HTTP traffic
  * const httpRule = await SecurityGroupRule("web-sg-http-rule", {
- *   securityGroup: webSecurityGroup,
+ *   securityGroup: webSg,
  *   type: "ingress",
  *   protocol: "tcp",
  *   fromPort: 80,
@@ -102,6 +168,33 @@ export interface SecurityGroup
  *   cidrBlocks: ["0.0.0.0/0"],
  *   description: "Allow HTTP access from anywhere"
  * });
+ * ```
+ *
+ * @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 SG uses scope credentials (main-account, us-west-2)
+ *   const mainSg = await SecurityGroup("main-sg", {
+ *     vpc: mainVpc,
+ *     groupName: "main-account-sg",
+ *     description: "Security group in main account",
+ *     tags: { Name: "main-account-sg" }
+ *   });
+ *
+ *   // This SG overrides to use different account
+ *   const crossAccountSg = await SecurityGroup("cross-account-sg", {
+ *     vpc: crossVpc,
+ *     groupName: "secondary-account-sg",
+ *     description: "Security group in secondary account",
+ *     profile: "secondary-account",
+ *     region: "us-east-1", // Also override region
+ *     tags: { Name: "secondary-account-sg" }
+ *   });
+ * });
+ * ```
  */
 export const SecurityGroup = Resource(
   "aws::SecurityGroup",
@@ -110,7 +203,8 @@ export const SecurityGroup = Resource(
     _id: string,
     props: SecurityGroupProps,
   ): Promise<SecurityGroup> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const vpcId = typeof props.vpc === "string" ? props.vpc : props.vpc.vpcId;
     const timeoutConfig = mergeTimeoutConfig(
       SECURITY_GROUP_TIMEOUT,

package/src/aws/ec2/subnet.ts

@@ -9,6 +9,7 @@ import {
   type TimeoutConfig,
   waitForResourceState,
 } from "../../util/timeout.ts";
+import type { AwsClientProps } from "../client-props.ts";
 import { retry } from "../retry.ts";
 import { callEC2Api, createEC2Client } from "./utils.ts";
 import type { Vpc } from "./vpc.ts";
@@ -16,7 +17,7 @@ import type { Vpc } from "./vpc.ts";
 /**
  * Properties for creating or updating a Subnet
  */
-export interface SubnetProps {
+export interface SubnetProps extends AwsClientProps {
   /**
    * The VPC to create the subnet in
    */
@@ -164,14 +165,15 @@ async function waitForSubnetDeleted(
  * AWS Subnet Resource
  *
  * Creates and manages subnets within a VPC. Subnets are used to segment
- * your VPC into smaller networks for organizing resources.
+ * your VPC into smaller networks for organizing resources. Supports AWS
+ * credential overrides for multi-account and cross-region deployments.
  *
  * @example
  * // Create a public subnet for web servers
  * const publicSubnet = await Subnet("public-subnet", {
  *   vpc: myVpc,
  *   cidrBlock: "10.0.1.0/24",
- *   availabilityZone: process.env.AWS_REGION ? `${process.env.AWS_REGION}a` : "us-east-1a",
+ *   availabilityZone: `${process.env.AWS_REGION}a` || "us-east-1a",
  *   mapPublicIpOnLaunch: true,
  *   tags: {
  *     Name: "public-subnet",
@@ -203,6 +205,62 @@ async function waitForSubnetDeleted(
  *     delayMs: 500
  *   }
  * });
+ *
+ * @example
+ * // Create a subnet with AWS credential overrides for cross-account deployment
+ * const crossAccountSubnet = await Subnet("cross-account-subnet", {
+ *   vpc: myVpc,
+ *   cidrBlock: "10.1.1.0/24",
+ *   availabilityZone: "us-east-1a",
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ *   mapPublicIpOnLaunch: true,
+ *   tags: {
+ *     Name: "cross-account-subnet",
+ *     Account: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a subnet in a different region with explicit credentials
+ * const multiRegionSubnet = await Subnet("multi-region-subnet", {
+ *   vpc: "vpc-12345678", // VPC ID from different region
+ *   cidrBlock: "10.2.1.0/24",
+ *   availabilityZone: "eu-west-1a",
+ *   region: "eu-west-1",
+ *   accessKeyId: alchemy.secret("AKIA..."),
+ *   secretAccessKey: alchemy.secret("..."),
+ *   mapPublicIpOnLaunch: false,
+ *   tags: {
+ *     Name: "eu-subnet",
+ *     Region: "europe"
+ *   }
+ * });
+ *
+ * @example
+ * // Using scope-level credentials with resource-level overrides
+ * await alchemy.run("multi-account", {
+ *   aws: {
+ *     region: "us-west-2",
+ *     profile: "staging"
+ *   }
+ * }, async () => {
+ *   // This subnet uses staging credentials from scope
+ *   const stagingSubnet = await Subnet("staging-subnet", {
+ *     vpc: stagingVpc,
+ *     cidrBlock: "10.0.1.0/24",
+ *     availabilityZone: "us-west-2a"
+ *   });
+ *
+ *   // This subnet overrides to use production credentials
+ *   const prodSubnet = await Subnet("prod-subnet", {
+ *     vpc: prodVpc,
+ *     cidrBlock: "10.1.1.0/24",
+ *     availabilityZone: "us-east-1a",
+ *     profile: "production",
+ *     region: "us-east-1"
+ *   });
+ * });
  */
 export const Subnet = Resource(
   "aws::Subnet",
@@ -211,7 +269,8 @@ export const Subnet = Resource(
     _id: string,
     props: SubnetProps,
   ): Promise<Subnet> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const vpcId = typeof props.vpc === "string" ? props.vpc : props.vpc.vpcId;
 
     // Validate timeout config early, but use default for deletion if invalid

package/src/aws/ec2/utils.ts

@@ -1,7 +1,11 @@
 import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
 import { AwsClient } from "aws4fetch";
+import { alchemy } from "../../alchemy.ts";
+import { Secret } from "../../secret.ts";
 import { logger } from "../../util/logger.ts";
 import { flattenParams } from "../../util/params.ts";
+import type { AwsClientProps } from "../client-props.ts";
+import { resolveAwsCredentials } from "../credentials.ts";
 import { getRegion } from "../utils.ts";
 
 /**
@@ -9,19 +13,81 @@ import { getRegion } from "../utils.ts";
  */
 
 /**
- * Create an AWS EC2 client
+ * Create an AWS EC2 client with credential resolution from props
+ *
+ * This function handles the complete credential resolution process internally,
+ * merging global, scope, and resource-level credentials according to the
+ * established precedence hierarchy.
+ *
+ * @param props - AWS client properties that may include credential overrides
+ * @returns Promise<AwsClient> - Configured AWS client for EC2 operations
  */
-export async function createEC2Client(): Promise<AwsClient> {
-  const credentials = await fromNodeProviderChain()();
-  const region = await getRegion();
+export async function createEC2Client(
+  props?: AwsClientProps,
+): Promise<AwsClient> {
+  // Resolve credentials from all sources (global, scope, resource)
+  const credentials = await resolveAwsCredentials(props);
+  let awsCredentials: AwsClientProps;
+  let region: string;
+
+  if (credentials && (credentials.accessKeyId || credentials.secretAccessKey)) {
+    // Use provided credentials directly (unwrap secrets for AWS SDK)
+    awsCredentials = {
+      accessKeyId: credentials.accessKeyId,
+      secretAccessKey: credentials.secretAccessKey,
+      sessionToken: credentials.sessionToken,
+    };
+  } else if (credentials?.profile) {
+    // Use profile-based credentials if profile is specified
+    try {
+      const profileCredentials = await fromNodeProviderChain({
+        profile: credentials.profile,
+      })();
+      awsCredentials = {
+        accessKeyId: alchemy.secret(profileCredentials.accessKeyId),
+        secretAccessKey: alchemy.secret(profileCredentials.secretAccessKey),
+        sessionToken: alchemy.secret(profileCredentials.sessionToken),
+      };
+    } catch (error) {
+      logger.log(
+        `Error loading credentials from profile ${credentials.profile}:`,
+        error,
+      );
+      // Fall back to default credentials
+      awsCredentials = await loadAwsPropsFromCredentialChain();
+    }
+  } else {
+    // Fall back to AWS SDK credential chain
+    awsCredentials = await loadAwsPropsFromCredentialChain();
+  }
+
+  // Use region from resolved credentials or fall back to getRegion()
+  if (credentials?.region) {
+    region = credentials.region;
+  } else {
+    region = await getRegion();
+  }
 
   return new AwsClient({
-    ...credentials,
+    ...awsCredentials,
+    accessKeyId: Secret.unwrap(awsCredentials.accessKeyId)!,
+    secretAccessKey: Secret.unwrap(awsCredentials.secretAccessKey)!,
+    sessionToken: Secret.unwrap(awsCredentials.sessionToken) || undefined,
     service: "ec2",
     region,
   });
 }
 
+async function loadAwsPropsFromCredentialChain(): Promise<AwsClientProps> {
+  const defaultCredentialsRaw = await fromNodeProviderChain()();
+  return {
+    ...defaultCredentialsRaw,
+    accessKeyId: alchemy.secret(defaultCredentialsRaw.accessKeyId),
+    secretAccessKey: alchemy.secret(defaultCredentialsRaw.secretAccessKey),
+    sessionToken: alchemy.secret(defaultCredentialsRaw.sessionToken),
+  };
+}
+
 /**
  * Make an EC2 API call with custom response parser
  */
@@ -34,8 +100,8 @@ export async function callEC2Api<T>(
   // Try the API call, and retry once with fresh credentials on auth failure
   for (let attempt = 1; attempt <= 2; attempt++) {
     try {
-      const region = await getRegion();
-      const url = `https://ec2.${region}.amazonaws.com/`;
+      // Use the client's region instead of the global region
+      const url = `https://ec2.${client.region}.amazonaws.com/`;
 
       const body = new URLSearchParams({
         Action: action,

package/src/aws/ec2/vpc.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 a VPC
  */
-export interface VpcProps {
+export interface VpcProps extends AwsClientProps {
   /**
    * The IPv4 network range for the VPC, in CIDR notation
    * @example "10.0.0.0/16"
@@ -148,7 +149,8 @@ export interface Vpc extends Resource<"aws::Vpc">, VpcProps {
  * AWS VPC (Virtual Private Cloud) Resource
  *
  * Creates and manages Amazon VPC instances with configurable CIDR blocks,
- * DNS settings, and instance tenancy options.
+ * DNS settings, and instance tenancy options. Supports AWS credential overrides
+ * for multi-account and cross-region deployments.
  *
  * @example
  * // Create a basic VPC with default settings
@@ -188,6 +190,52 @@ export interface Vpc extends Resource<"aws::Vpc">, VpcProps {
  *     Type: "isolated"
  *   }
  * });
+ *
+ * @example
+ * // Create a VPC with AWS credential overrides for cross-account deployment
+ * const crossAccountVpc = await Vpc("cross-account-vpc", {
+ *   cidrBlock: "10.1.0.0/16",
+ *   region: "us-east-1",
+ *   profile: "production-account",
+ *   tags: {
+ *     Name: "cross-account-vpc",
+ *     Account: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a VPC in a different region with explicit credentials
+ * const multiRegionVpc = await Vpc("multi-region-vpc", {
+ *   cidrBlock: "10.2.0.0/16",
+ *   region: "eu-west-1",
+ *   accessKeyId: alchemy.secret("AKIA..."),
+ *   secretAccessKey: alchemy.secret("..."),
+ *   tags: {
+ *     Name: "eu-vpc",
+ *     Region: "europe"
+ *   }
+ * });
+ *
+ * @example
+ * // Using scope-level credentials with resource-level overrides
+ * await alchemy.run("multi-account", {
+ *   aws: {
+ *     region: "us-west-2",
+ *     profile: "staging"
+ *   }
+ * }, async () => {
+ *   // This VPC uses staging credentials from scope
+ *   const stagingVpc = await Vpc("staging-vpc", {
+ *     cidrBlock: "10.0.0.0/16"
+ *   });
+ *
+ *   // This VPC overrides to use production credentials
+ *   const prodVpc = await Vpc("prod-vpc", {
+ *     cidrBlock: "10.1.0.0/16",
+ *     profile: "production",
+ *     region: "us-east-1"
+ *   });
+ * });
  */
 export const Vpc = Resource(
   "aws::Vpc",
@@ -196,7 +244,8 @@ export const Vpc = Resource(
     _id: string,
     props: VpcProps,
   ): Promise<Vpc> {
-    const client = await createEC2Client();
+    // Create EC2 client with credential resolution handled internally
+    const client = await createEC2Client(props);
     const timeoutConfig = mergeTimeoutConfig(VPC_TIMEOUT, props.timeout);
 
     if (this.phase === "delete") {

package/src/aws/index.ts

@@ -1,5 +1,7 @@
 export * from "./account-id.ts";
 export * from "./bucket.ts";
+export * from "./client-props.ts";
+export * from "./credentials.ts";
 export * from "./function.ts";
 export * from "./policy-attachment.ts";
 export * from "./policy.ts";

package/src/cloudflare/api-response.ts

@@ -102,8 +102,8 @@ export async function extractCloudflareResult<T>(
   label: string,
   promise: Promise<Response>,
 ): Promise<T> {
-  const response = await promise.catch(() => {
-    throw new Error(`Failed to ${label}: Failed to fetch`);
+  const response = await promise.catch((cause) => {
+    throw new Error(`Failed to ${label}: Failed to fetch`, { cause });
   });
   const json = (await response.json().catch(() => {
     throw new Error(

package/src/cloudflare/api.ts

@@ -63,6 +63,10 @@ const cloudflareApiCache: Record<string, CloudflareApi> = {};
 export async function createCloudflareApi(
   options: Partial<CloudflareApiOptions> | InternalCloudflareApiOptions = {},
 ): Promise<CloudflareApi> {
+  // TODO: Implement scope-level credential resolution similar to AWS
+  // This function should check for scope.providerCredentials.cloudflare
+  // and merge those credentials with the provided options, following
+  // the same three-tier resolution pattern: global → scope → resource
   const cacheKey = computeCacheKey(options);
   if (cloudflareApiCache[cacheKey]) {
     return cloudflareApiCache[cacheKey];
@@ -251,3 +255,22 @@ class TooManyRequestsError extends Error {
 }
 
 class ForbiddenError extends Error {}
+/**
+ * Cloudflare scope extensions - adds Cloudflare credential support to scope options.
+ * This uses TypeScript module augmentation to extend the ProviderCredentials interface.
+ * Since ScopeOptions and RunOptions both extend ProviderCredentials,
+ * they automatically inherit these properties.
+ *
+ * NOTE: These scope credentials are not currently being used by createCloudflareApi.
+ * See TODO above in createCloudflareApi function for implementation needed.
+ */
+declare module "../scope.ts" {
+  interface ProviderCredentials {
+    /**
+     * Cloudflare credentials configuration for this scope.
+     * All Cloudflare resources created within this scope will inherit these credentials
+     * unless overridden at the resource level.
+     */
+    cloudflare?: CloudflareApiOptions;
+  }
+}

package/src/cloudflare/assets.ts

@@ -1,5 +1,5 @@
 import * as fs from "node:fs/promises";
-import * as path from "node:path";
+import * as path from "pathe";
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { getContentType } from "../util/content-type.ts";
@@ -118,11 +118,10 @@ export const Assets = Resource(
     // Create asset file objects
     const files: AssetFile[] = filesList.map((filePath) => {
       const relativePath = path.relative(props.path, filePath);
-      const normalizedPath = relativePath.split(path.sep).join("/"); // Ensure forward slashes for URLs
 
       return {
-        path: normalizedPath,
-        filePath,
+        path: path.normalize(relativePath),
+        filePath: path.normalize(filePath),
         contentType: getContentType(filePath) ?? "application/null",
       };
     });