alchemy 0.60.2 → 0.62.0

package/lib/util/safe-fetch.js

@@ -52,4 +52,76 @@ async function dispatcher() {
     }
     return agent.value;
 }
+/**
+ * Fetch with exponential backoff retry logic for 404 responses, expecting 200 OK.
+ * This is a convenience wrapper around fetchAndExpectStatus with expectedStatus=200.
+ *
+ * @param input URL or Request object
+ * @param init RequestInit options
+ * @param maxAttempts Maximum number of retry attempts (default: 10)
+ * @param maxWaitTime Maximum total wait time in milliseconds (default: 30000)
+ * @returns The successful Response
+ */
+export async function fetchAndExpectOK(input, init, maxAttempts = 10, maxWaitTime = 30000) {
+    return fetchAndExpectStatus(input, init, 200, maxAttempts, maxWaitTime);
+}
+/**
+ * Fetch and expect a specific status code with retry logic.
+ * Cloudflare's control plane is eventually consistent, so resources may
+ * return 404 immediately after creation before becoming available.
+ *
+ * @param input URL or Request object
+ * @param init RequestInit options
+ * @param expectedStatus Expected HTTP status code (default: 200)
+ * @param maxAttempts Maximum number of retry attempts (default: 10)
+ * @param maxWaitTime Maximum total wait time in milliseconds (default: 30000)
+ * @returns The successful Response
+ */
+export async function fetchAndExpectStatus(input, init, expectedStatus = 200, maxAttempts = 20, maxWaitTime = 30000) {
+    let attempt = 0;
+    let lastError;
+    while (attempt < maxAttempts) {
+        try {
+            const response = await safeFetch(input, init);
+            // If we get the expected status, return it
+            if (response.status === expectedStatus) {
+                return response;
+            }
+            // If we get a 500, 404 when expecting something else, retry with backoff
+            if (response.status >= 500 ||
+                (response.status === 404 && expectedStatus !== 404)) {
+                attempt++;
+                if (attempt >= maxAttempts) {
+                    throw new Error(`Expected status ${expectedStatus} but got 404 after ${maxAttempts} attempts. This may indicate eventual consistency issues.`);
+                }
+                const backoffTime = Math.min(attempt * 1500, maxWaitTime / maxAttempts);
+                console.log(`Expected status ${expectedStatus} but got 404, retrying in ${backoffTime}ms (attempt ${attempt}/${maxAttempts})...`);
+                await new Promise((resolve) => setTimeout(resolve, backoffTime));
+                continue;
+            }
+            // For other status codes, throw immediately
+            throw new Error(`Expected status ${expectedStatus} but got ${response.status}: ${response.statusText}`);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                lastError = error;
+                // If it's not an HTTP error, retry with backoff
+                if (!error.message.startsWith("Expected status") &&
+                    !error.message.startsWith("HTTP ")) {
+                    attempt++;
+                    if (attempt >= maxAttempts) {
+                        break;
+                    }
+                    const backoffTime = Math.min(attempt * 1500, maxWaitTime / maxAttempts);
+                    console.log(`Network error, retrying in ${backoffTime}ms (attempt ${attempt}/${maxAttempts}): ${error.message}`);
+                    await new Promise((resolve) => setTimeout(resolve, backoffTime));
+                    continue;
+                }
+            }
+            // For status code mismatches, throw immediately
+            throw error;
+        }
+    }
+    throw lastError || new Error(`Failed after ${maxAttempts} attempts`);
+}
 //# sourceMappingURL=safe-fetch.js.map

package/lib/util/safe-fetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fetch.js","sourceRoot":"","sources":["../../src/util/safe-fetch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAA2B,EAC3B,UAAuB,EAAE,EACzB,OAAO,GAAG,EAAE;IAEZ,IAAI,SAAc,CAAC;IACnB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,KAAK,CAAC,GAAG,EAAE;gBACtB,GAAG,OAAO;gBACV,oEAAoE;gBACpE,UAAU,EAAE,MAAM,UAAU,EAAE;aAChB,CAAC,CAAC;QACpB,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxB,SAAS,GAAG,GAAG,CAAC;YAChB,MAAM,WAAW,GACf,uBAAuB,CAAC,GAAG,CAAC,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAErE,IAAI,CAAC,WAAW,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBACxC,MAAM,GAAG,CAAC;YACZ,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,SAAS,OAAO,IAAI,OAAO,QAAQ,GAAG,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YACnE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,sBAAsB;QAChF,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC;AAED,SAAS,uBAAuB,CAAC,GAAQ;IACvC,OAAO,CACL,GAAG,EAAE,IAAI,KAAK,gBAAgB;QAC9B,GAAG,EAAE,IAAI,KAAK,YAAY;QAC1B,GAAG,EAAE,IAAI,KAAK,yBAAyB;QACvC,GAAG,EAAE,IAAI,KAAK,OAAO;QACrB,GAAG,EAAE,IAAI,KAAK,YAAY,CAC3B,CAAC;AACJ,CAAC;AAED,IAAI,KAIS,CAAC;AAEd,KAAK,UAAU,UAAU;IACvB,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IACD,IAAI,CAAC;QACH,uCAAuC;QACvC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEzC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,gEAAgE;YAChE,KAAK,GAAG;gBACN,KAAK,EAAE,IAAI,KAAK,CAAC;oBACf,UAAU,EAAE,CAAC,EAAE,gDAAgD;oBAC/D,2DAA2D;iBAC5D,CAAC;aACH,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC;AACrB,CAAC"}
+{"version":3,"file":"safe-fetch.js","sourceRoot":"","sources":["../../src/util/safe-fetch.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.60.2",
+  "version": "0.62.0",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
   "homepage": "https://alchemy.run",
@@ -149,6 +149,10 @@
       "bun": "./src/state/index.ts",
       "import": "./lib/state/index.js"
     },
+    "./util": {
+      "bun": "./src/util/index.ts",
+      "import": "./lib/util/index.js"
+    },
     "./web/astro": {
       "bun": "./src/web/astro.ts",
       "import": "./lib/web/astro.js"
@@ -168,7 +172,7 @@
   },
   "dependencies": {
     "@aws-sdk/credential-providers": "^3.0.0",
-    "@cloudflare/unenv-preset": "^2.4.0",
+    "@cloudflare/unenv-preset": "^2.6.1",
     "@cloudflare/workers-shared": "^0.17.5",
     "@iarna/toml": "^2.2.5",
     "@smithy/node-config-provider": "^4.0.0",
@@ -180,9 +184,10 @@
     "execa": "^9.6.0",
     "fast-json-patch": "^3.1.1",
     "fast-xml-parser": "^5.2.5",
+    "find-process": "^2.0.0",
     "glob": "^10.0.0",
+    "picocolors": "^1.1.1",
     "jszip": "^3.0.0",
-    "kleur": "^4.1.5",
     "libsodium-wrappers": "^0.7.15",
     "miniflare": "^4.20250712.0",
     "neverthrow": "^8.2.0",
@@ -191,7 +196,7 @@
     "pathe": "^2.0.3",
     "signal-exit": "^4.1.0",
     "turndown": "^7.0.0",
-    "unenv": "2.0.0-rc.15",
+    "unenv": "2.0.0-rc.19",
     "ws": "^8.18.3",
     "yaml": "^2.0.0"
   },
@@ -259,7 +264,6 @@
     "nitro-cloudflare-dev": "^0.2.2",
     "nitropack": "^2.12.4",
     "openpgp": "^6.1.0",
-    "picocolors": "^1.1.1",
     "prettier": "^3.5.3",
     "rwsdk": "^0.1.28",
     "trpc-cli": "^0.10.2",

package/src/alchemy.ts

@@ -15,7 +15,7 @@ import {
   type PendingResource,
 } from "./resource.ts";
 import { isRuntime } from "./runtime/global.ts";
-import { DEFAULT_STAGE, Scope } from "./scope.ts";
+import { DEFAULT_STAGE, Scope, type ProviderCredentials } from "./scope.ts";
 import { secret } from "./secret.ts";
 import type { StateStoreType } from "./state.ts";
 import type { LoggerApi } from "./util/cli.ts";
@@ -193,6 +193,7 @@ If this is a mistake, you can disable this check by setting the ALCHEMY_CI_STATE
     });
     onExit((code) => {
       root.cleanup().then(() => {
+        code = code === 130 ? 0 : (code ?? 0);
         process.exit(code);
       });
       return true;
@@ -419,7 +420,7 @@ export interface ScopeOptions extends AlchemyOptions {
   enter: boolean;
 }
 
-export interface RunOptions extends AlchemyOptions {
+export interface RunOptions extends AlchemyOptions, ProviderCredentials {
   /**
    * @default false
    */

package/src/aws/client-props.ts

@@ -0,0 +1,156 @@
+import type { Secret } from "../secret.ts";
+
+/**
+ * AWS client properties for credential configuration.
+ *
+ * This interface defines the properties that can be used to configure AWS credentials
+ * at different levels of your application. It supports the three-tier credential resolution
+ * system (global → scope → resource) and enables multi-account and multi-region deployments.
+ *
+ * These properties can be specified at:
+ * 1. Resource level - directly in resource creation parameters
+ * 2. Scope level - in alchemy.run() options with `aws` property
+ * 3. Global level - through environment variables (AWS_REGION, AWS_PROFILE, etc.)
+ *
+ * The credential resolution follows a precedence order where resource-level credentials
+ * override scope-level credentials, which override global environment variables.
+ *
+ * @example
+ * ```typescript
+ * // Resource-level credential overrides
+ * const vpc = await Vpc("main-vpc", {
+ *   cidrBlock: "10.0.0.0/16",
+ *   region: "us-west-2",      // Override region
+ *   profile: "production",    // Override profile
+ *   tags: { Name: "main-vpc" }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Scope-level credential configuration
+ * await alchemy.run("production", {
+ *   aws: {
+ *     region: "us-west-2",
+ *     profile: "production",
+ *   }
+ * }, async () => {
+ *   // Resources created here will use the scope credentials by default
+ *   const vpc = await Vpc("main-vpc", {
+ *     cidrBlock: "10.0.0.0/16"
+ *   });
+ * });
+ * ```
+ */
+export interface AwsClientProps {
+  /**
+   * AWS access key ID for authentication.
+   *
+   * This corresponds to the AWS_ACCESS_KEY_ID environment variable.
+   * When provided at the resource or scope level, it overrides the environment variable.
+   */
+  accessKeyId?: Secret<string>;
+
+  /**
+   * AWS secret access key for authentication.
+   *
+   * This corresponds to the AWS_SECRET_ACCESS_KEY environment variable.
+   * When provided at the resource or scope level, it overrides the environment variable.
+   */
+  secretAccessKey?: Secret<string>;
+
+  /**
+   * AWS session token for temporary credentials.
+   *
+   * This corresponds to the AWS_SESSION_TOKEN environment variable.
+   * Used with temporary credentials from STS or when assuming a role.
+   */
+  sessionToken?: Secret<string>;
+
+  /**
+   * AWS region to use for API calls.
+   *
+   * This corresponds to the AWS_REGION or AWS_DEFAULT_REGION environment variables.
+   * When provided at the resource or scope level, it overrides the environment variables.
+   *
+   * @example
+   * ```typescript
+   * // Resource in a specific region
+   * const euVpc = await Vpc("eu-vpc", {
+   *   cidrBlock: "10.0.0.0/16",
+   *   region: "eu-west-1",
+   *   tags: { Name: "eu-vpc" }
+   * });
+   * ```
+   */
+  region?: string;
+
+  /**
+   * AWS profile name to use from credentials file.
+   *
+   * This corresponds to the AWS_PROFILE environment variable.
+   * Profiles are defined in ~/.aws/credentials or ~/.aws/config files.
+   *
+   * @example
+   * ```typescript
+   * // Resource using a specific profile
+   * const prodVpc = await Vpc("prod-vpc", {
+   *   cidrBlock: "10.0.0.0/16",
+   *   profile: "production-account",
+   *   tags: { Name: "prod-vpc" }
+   * });
+   * ```
+   */
+  profile?: string;
+
+  /**
+   * AWS role ARN to assume for authentication.
+   *
+   * This corresponds to the AWS_ROLE_ARN environment variable.
+   * Used for cross-account access or for assuming roles with specific permissions.
+   *
+   * @example
+   * ```typescript
+   * // Resource using role assumption
+   * const crossAccountVpc = await Vpc("cross-account-vpc", {
+   *   cidrBlock: "10.0.0.0/16",
+   *   roleArn: "arn:aws:iam::123456789012:role/DeploymentRole",
+   *   roleSessionName: "alchemy-deployment",
+   *   tags: { Name: "cross-account-vpc" }
+   * });
+   * ```
+   */
+  roleArn?: string;
+
+  /**
+   * External ID to use when assuming a role.
+   *
+   * This corresponds to the AWS_EXTERNAL_ID environment variable.
+   * Used as an additional security measure when assuming roles across accounts.
+   */
+  externalId?: string;
+
+  /**
+   * Session name to use when assuming a role.
+   *
+   * This corresponds to the AWS_ROLE_SESSION_NAME environment variable.
+   * Helps identify who/what is using the assumed role in AWS CloudTrail logs.
+   */
+  roleSessionName?: string;
+}
+/**
+ * AWS scope extensions - adds AWS 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.
+ */
+declare module "../scope.ts" {
+  interface ProviderCredentials {
+    /**
+     * AWS credentials configuration for this scope.
+     * All AWS resources created within this scope will inherit these credentials
+     * unless overridden at the resource level.
+     */
+    aws?: AwsClientProps;
+  }
+}

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,