feat(credential-providers): Add a cli v2 compatible credential provider

packages/credential-providers/README.md

@@ -27,6 +27,8 @@ A collection of all credential providers.
    1. [Sample Files](#sample-files-2)
 1. [From Node.js default credentials provider chain](#fromnodeproviderchain)
 1. [Creating a custom credentials chain](#createcredentialchain)
+1. [Aws CliV2 Region resolution order](#resolveAwsCliV2Region)
+1. [From AwsCliV2 compatible provider chain](#fromAwsCliV2CompatibleProviderChain)
 
 ## Terminology
 
@@ -825,7 +827,7 @@ Successfully signed out of all SSO profiles.
 ### Sample files
 
 This credential provider is only applicable if the profile specified in shared configuration and
-credentials files contain ALL of the following entries.
+credentials files contain ALL the following entries.
 
 #### `~/.aws/credentials`
 
@@ -948,6 +950,67 @@ new S3({
 });
 ```
 
+## `fromAwsCliV2CompatibleProviderChain()`
+
+- Not available in browsers & native apps.
+
+A credential provider that follows the same priority order as the AWS CLI v2 credential resolution.
+This credential provider will attempt to find credentials from the following sources (listed in
+order of precedence):
+
+- Inline code static credentials
+- **when a profile is specified**:
+  - Same resolution as the [fromIni](#fromini) provider.
+- **when a profile is not specified**:
+  - [Environment variables exposed via `process.env`](#fromenv)
+  - [Web identity token credentials](#fromtokenfile)
+  - [SSO credentials from token cache](#fromsso)
+  - [From Credential Process](#fromprocess)
+  - [From Instance and Container Metadata Service](#fromcontainermetadata-and-frominstancemetadata)
+
+```js
+import { fromAwsCliV2CompatibleProviderChain, resolveAwsCliV2Region } from "@aws-sdk/credential-providers";
+import { S3Client } from "@aws-sdk/client-s3";
+
+const s3Client = new S3Client({
+  profile: "my-profile",
+
+  // Implements AWS CLI v2-compatible credential resolution and proxy settings.
+  credentials: fromAwsCliV2CompatibleProviderChain({}),
+
+  // Implements AWS CLI v2 region resolution logic.
+  region: resolveAwsCliV2Region({
+    // (!) this duplication is required if not using the "default" profile.
+    profile: "my-profile",
+    defaultRegion: "us-east-1", // optional
+  }),
+});
+```
+
+### `resolveAwsCliV2Region()`
+
+- This is not a credential resolver. It is a region resolver included here for ease of access.
+- Not available in browsers & native apps.
+
+The region is resolved using the following order of precedence (highest to lowest) in the cli v2.
+
+1. Environment Variables
+   - AWS_REGION
+   - AWS_DEFAULT_REGION
+2. AWS Configuration Files
+   - Profile specific region from ~/.aws/config or ~/.aws/credentials
+   - Profile selection order:
+     1. Explicitly provided profile
+     2. AWS_PROFILE environment variable
+     3. AWS_DEFAULT_PROFILE environment variable
+     4. "default" profile
+3. EC2/ECS Instance Metadata Service
+   - Region from instance identity document
+   - Automatically falls back if metadata service is unavailable
+4. Default Region
+   - Uses provided default region if specified
+   - Returns undefined if no region can be determined
+
 ## Add Custom Headers to STS assume-role calls
 
 You can specify the plugins--groups of middleware, to inject to the STS client.

packages/credential-providers/package.json

@@ -40,11 +40,13 @@
     "@aws-sdk/credential-provider-process": "*",
     "@aws-sdk/credential-provider-sso": "*",
     "@aws-sdk/credential-provider-web-identity": "*",
+    "@aws-sdk/ec2-metadata-service": "*",
     "@aws-sdk/nested-clients": "*",
     "@aws-sdk/types": "*",
     "@smithy/core": "^3.1.5",
     "@smithy/credential-provider-imds": "^4.0.1",
     "@smithy/property-provider": "^4.0.1",
+    "@smithy/shared-ini-file-loader": "^4.0.1",
     "@smithy/types": "^4.1.0",
     "tslib": "^2.6.2"
   },

packages/credential-providers/src/fromAwsCliV2CompatibleProviderChain.spec.ts

@@ -0,0 +1,86 @@
+import type { Exact } from "@smithy/types";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  AwsCliV2CompatibleProviderOptions,
+  fromAwsCliV2CompatibleProviderChain,
+} from "./fromAwsCliV2CompatibleProviderChain";
+
+// the options type should have no required fields.
+type Assert = Exact<AwsCliV2CompatibleProviderOptions, Partial<AwsCliV2CompatibleProviderOptions>>;
+const typeAssertion: Assert = true as const;
+void typeAssertion;
+
+describe("fromAwsCliV2CompatibleProviderChain", () => {
+  let mockFromIni: any;
+  let mockFromNodeProviderChain: any;
+
+  const mockLogger = {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+
+    mockFromIni = vi.fn(() =>
+      vi.fn(async () => ({
+        accessKeyId: "PROFILE_ACCESS_KEY",
+        secretAccessKey: "PROFILE_SECRET_KEY",
+      }))
+    );
+    vi.doMock("@aws-sdk/credential-provider-ini", () => ({
+      fromIni: mockFromIni,
+    }));
+
+    mockFromNodeProviderChain = vi.fn(() =>
+      vi.fn(async () => ({
+        accessKeyId: "AWS_SDK_CHAIN_AK",
+        secretAccessKey: "AWS_SDK_CHAIN_SK",
+      }))
+    );
+    vi.doMock("@aws-sdk/credential-provider-node", () => ({
+      defaultProvider: mockFromNodeProviderChain,
+    }));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should use profile credentials when profile is specified", async () => {
+    const provider = fromAwsCliV2CompatibleProviderChain({
+      profile: "test-profile",
+      logger: mockLogger,
+    });
+
+    const result = await provider();
+
+    expect(result).toEqual({
+      accessKeyId: "PROFILE_ACCESS_KEY",
+      secretAccessKey: "PROFILE_SECRET_KEY",
+    });
+
+    expect(mockFromIni).toHaveBeenCalled();
+    expect(mockLogger.debug).toHaveBeenCalledWith(
+      `@aws-sdk/credential-providers - fromAwsCliV2CompatibleProviderChain - Using fromIni with profile: test-profile`
+    );
+  });
+
+  it.only("should fall back to fromNodeProviderChain when no profile is specified", async () => {
+    const provider = fromAwsCliV2CompatibleProviderChain({
+      logger: console,
+    });
+
+    const result = await provider();
+
+    expect(result).toEqual({
+      accessKeyId: "AWS_SDK_CHAIN_AK",
+      secretAccessKey: "AWS_SDK_CHAIN_SK",
+    });
+    expect(mockFromNodeProviderChain).toHaveBeenCalled();
+  });
+});

packages/credential-providers/src/fromAwsCliV2CompatibleProviderChain.ts

@@ -0,0 +1,66 @@
+import type { DefaultProviderInit } from "@aws-sdk/credential-provider-node";
+import type { RuntimeConfigAwsCredentialIdentityProvider } from "@aws-sdk/types";
+import type { AwsCredentialIdentity } from "@smithy/types";
+
+/**
+ * @public
+ */
+export type AwsCliV2CompatibleProviderOptions = Partial<AwsCredentialIdentity> & DefaultProviderInit;
+
+/**
+ * Creates an alternate form of the AWS SDK for JavaScript's fromNodeProviderChain.
+ * This differs in ways that makes it behave more like the AWS CLI v2:
+ * 1. It allows inline static credentials.
+ * 2. It checks AWS_DEFAULT_PROFILE in addition to AWS_PROFILE.
+ * 3. It prioritizes fromIni if a profile is set.
+ * Otherwise, it behaves as fromNodeProviderChain.
+ *
+ * @public
+ *
+ * @param _init - Configuration options for the provider chain.
+ * @returns An AWS credential provider.
+ */
+export const fromAwsCliV2CompatibleProviderChain =
+  (_init: AwsCliV2CompatibleProviderOptions = {}): RuntimeConfigAwsCredentialIdentityProvider =>
+  async ({ callerClientConfig } = {}): Promise<AwsCredentialIdentity> => {
+    // Merge init with caller's client config (profile/region).
+    const init: AwsCliV2CompatibleProviderOptions = {
+      ..._init,
+      profile:
+        _init.profile ?? callerClientConfig?.profile ?? process.env.AWS_PROFILE ?? process.env.AWS_DEFAULT_PROFILE,
+      logger: _init.logger ?? callerClientConfig?.logger,
+    };
+    const { profile, accessKeyId, secretAccessKey, sessionToken, expiration, accountId } = init;
+
+    const debug = init.logger?.debug ?? (() => {});
+
+    debug("@aws-sdk/credential-providers - fromAwsCliV2CompatibleProviderChain - init");
+
+    // 1. If credentials are explicitly provided, return them.
+    if (accessKeyId && secretAccessKey) {
+      debug("@aws-sdk/credential-providers - fromAwsCliV2CompatibleProviderChain - static credentials from init");
+      return {
+        accessKeyId,
+        secretAccessKey,
+        ...(sessionToken && { sessionToken }),
+        ...(expiration && { expiration }),
+        ...(accountId && { accountId }),
+      } as AwsCredentialIdentity;
+    }
+
+    // 2. If a profile is explicitly passed, use `fromIni`.
+    if (profile) {
+      debug(
+        `@aws-sdk/credential-providers - fromAwsCliV2CompatibleProviderChain - Using fromIni with profile: ${profile}`
+      );
+      const { fromIni } = await import("@aws-sdk/credential-provider-ini");
+      return fromIni(init)({ callerClientConfig });
+    }
+
+    // 3. Defer to AWS SDK credential chain.
+    debug("@aws-sdk/credential-providers - fromAwsCliV2CompatibleProviderChain - defer to fromNodeProviderChain");
+    const { defaultProvider: fromNodeProviderChain } = await import("@aws-sdk/credential-provider-node");
+    return fromNodeProviderChain(init)({
+      // todo: fromNodeProviderChain should be changed to RuntimeConfigAwsCredentialIdentityProvider.
+    });
+  };

packages/credential-providers/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./createCredentialChain";
+export * from "./fromAwsCliV2CompatibleProviderChain";
 export * from "./fromCognitoIdentity";
 export * from "./fromCognitoIdentityPool";
 export * from "./fromContainerMetadata";
@@ -12,3 +13,4 @@ export * from "./fromSSO";
 export * from "./fromTemporaryCredentials";
 export * from "./fromTokenFile";
 export * from "./fromWebToken";
+export { resolveAwsCliV2Region } from "./resolveAwsCliV2Region";