@aws-sdk/credential-providers 3.629.0 → 3.630.0

package/README.md

@@ -25,6 +25,7 @@ A collection of all credential providers, with default clients.
    1. [SSO login with AWS CLI](#sso-login-with-the-aws-cli)
    1. [Sample Files](#sample-files-2)
 1. [From Node.js default credentials provider chain](#fromNodeProviderChain)
+1. [Creating a custom credentials chain](#createCredentialChain)
 
 ## `fromCognitoIdentity()`
 
@@ -704,14 +705,14 @@ CLI profile name [123456789011_ReadOnly]: my-sso-profile<ENTER>
 
 ```javascript
 //...
-const client = new FooClient({ credentials: fromSSO({ profile: "my-sso-profile" })});
+const client = new FooClient({ credentials: fromSSO({ profile: "my-sso-profile" }) });
 ```
 
 Alternatively, the SSO credential provider is supported in shared INI credentials provider
 
 ```javascript
 //...
-const client = new FooClient({ credentials: fromIni({ profile: "my-sso-profile" })});
+const client = new FooClient({ credentials: fromIni({ profile: "my-sso-profile" }) });
 ```
 
 3. To log out from the current SSO session, use the AWS CLI:
@@ -784,6 +785,60 @@ const credentialProvider = fromNodeProviderChain({
 });
 ```
 
+## `createCredentialChain()`
+
+You can use this helper to create a credential chain of your own.
+
+A credential chain is created from a list of functions of the signature () => Promise<[AwsCredentialIdentity](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-types/Interface/AwsCredentialIdentity/)>,
+composed together such that the overall chain has the **same** signature.
+
+That is why you can provide the chained credential provider to the same field (`credentials`) as any single provider function.
+
+All the providers from this package are compatible, and can be used to create such a chain.
+
+As with _any_ function provided to the `credentials` SDK client constructor configuration field, if the credential object returned does not contain
+an `expiration` (type `Date`), the client will only ever call the provider function once. You do not need to memoize this function.
+
+To enable automatic refresh, the credential provider function should set an `expiration` (`Date`) field. When this expiration approaches within 5 minutes, the 
+provider function will be called again by the client in the course of making SDK requests.
+
+To assist with this, the `createCredentialChain` has a chainable helper `.expireAfter(milliseconds: number)`. An example is included below.
+
+```ts
+import { fromEnv, fromIni, createCredentialChain } from "@aws-sdk/credential-providers";
+import { S3 } from "@aws-sdk/client-s3";
+
+// You can mix existing AWS SDK credential providers
+// and custom async functions returning credential objects.
+new S3({
+  credentials: createCredentialChain(
+    fromEnv(),
+    async () => {
+      // credentials customized by your code...
+      return credentials;
+    },
+    fromIni()
+  ),
+});
+
+// Set a max duration on the credentials (client side only).
+// A set expiration will cause the credentials function to be called again
+// when the time left is less than 5 minutes.
+new S3({
+  // This setting indicates expiry after 15 minutes (in milliseconds) with `15 * 60_000`.
+  // Due to the 5 minute expiry window, the function will be called approximately every
+  // 10 minutes under continuous usage of this client.
+  credentials: createCredentialChain(fromEnv(), fromIni()).expireAfter(15 * 60_000),
+});
+
+// Apply shared init properties.
+const init = { logger: console };
+
+new S3({
+  credentials: createCredentialChain(fromEnv(init), fromIni(init)),
+});
+```
+
 ## Add Custom Headers to STS assume-role calls
 
 You can specify the plugins--groups of middleware, to inject to the STS client.

package/dist-cjs/createCredentialChain.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCredentialChain = void 0;
+const property_provider_1 = require("@smithy/property-provider");
+const createCredentialChain = (...credentialProviders) => {
+    let expireAfter = -1;
+    const baseFunction = async () => {
+        const credentials = await (0, property_provider_1.chain)(...credentialProviders)();
+        if (!credentials.expiration && expireAfter !== -1) {
+            credentials.expiration = new Date(Date.now() + expireAfter);
+        }
+        return credentials;
+    };
+    const withOptions = Object.assign(baseFunction, {
+        expireAfter(milliseconds) {
+            if (milliseconds < 5 * 60000) {
+                throw new Error("@aws-sdk/credential-providers - createCredentialChain(...).expireAfter(ms) may not be called with a duration lower than five minutes.");
+            }
+            expireAfter = milliseconds;
+            return withOptions;
+        },
+    });
+    return withOptions;
+};
+exports.createCredentialChain = createCredentialChain;

package/dist-cjs/index.js

@@ -2,12 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromHttp = void 0;
 const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./createCredentialChain"), exports);
 tslib_1.__exportStar(require("./fromCognitoIdentity"), exports);
 tslib_1.__exportStar(require("./fromCognitoIdentityPool"), exports);
 tslib_1.__exportStar(require("./fromContainerMetadata"), exports);
-tslib_1.__exportStar(require("./fromEnv"), exports);
 var credential_provider_http_1 = require("@aws-sdk/credential-provider-http");
 Object.defineProperty(exports, "fromHttp", { enumerable: true, get: function () { return credential_provider_http_1.fromHttp; } });
+tslib_1.__exportStar(require("./fromEnv"), exports);
 tslib_1.__exportStar(require("./fromIni"), exports);
 tslib_1.__exportStar(require("./fromInstanceMetadata"), exports);
 tslib_1.__exportStar(require("./fromNodeProviderChain"), exports);

package/dist-es/createCredentialChain.js

@@ -0,0 +1,21 @@
+import { chain as propertyProviderChain } from "@smithy/property-provider";
+export const createCredentialChain = (...credentialProviders) => {
+    let expireAfter = -1;
+    const baseFunction = async () => {
+        const credentials = await propertyProviderChain(...credentialProviders)();
+        if (!credentials.expiration && expireAfter !== -1) {
+            credentials.expiration = new Date(Date.now() + expireAfter);
+        }
+        return credentials;
+    };
+    const withOptions = Object.assign(baseFunction, {
+        expireAfter(milliseconds) {
+            if (milliseconds < 5 * 60000) {
+                throw new Error("@aws-sdk/credential-providers - createCredentialChain(...).expireAfter(ms) may not be called with a duration lower than five minutes.");
+            }
+            expireAfter = milliseconds;
+            return withOptions;
+        },
+    });
+    return withOptions;
+};

package/dist-es/index.js

@@ -1,8 +1,9 @@
+export * from "./createCredentialChain";
 export * from "./fromCognitoIdentity";
 export * from "./fromCognitoIdentityPool";
 export * from "./fromContainerMetadata";
-export * from "./fromEnv";
 export { fromHttp } from "@aws-sdk/credential-provider-http";
+export * from "./fromEnv";
 export * from "./fromIni";
 export * from "./fromInstanceMetadata";
 export * from "./fromNodeProviderChain";

package/dist-types/createCredentialChain.d.ts

@@ -0,0 +1,44 @@
+import type { AwsCredentialIdentityProvider } from "@smithy/types";
+export interface CustomCredentialChainOptions {
+    expireAfter(milliseconds: number): AwsCredentialIdentityProvider & CustomCredentialChainOptions;
+}
+/**
+ * @example
+ * ```js
+ * import { fromEnv, fromIni, createCredentialChain } from '@aws-sdk/credential-providers';
+ * import { S3 } from '@aws-sdk/client-s3';
+ *
+ * // You can mix existing AWS SDK credential providers
+ * // and custom async functions returning credential objects.
+ * new S3({
+ *   credentials: createCredentialChain(
+ *     fromEnv(),
+ *     async () => {
+ *       // credentials customized by your code...
+ *       return credentials;
+ *     },
+ *     fromIni()
+ *   ),
+ * });
+ *
+ * // Set a max duration on the credentials (client side only).
+ * // A set expiration will cause the credentials function to be called again
+ * // when the time left is less than 5 minutes.
+ * new S3({
+ *   // expire after 15 minutes (in milliseconds).
+ *   credentials: createCredentialChain(fromEnv(), fromIni()).expireAfter(15 * 60_000),
+ * });
+ *
+ * // Apply shared init properties.
+ * const init = { logger: console };
+ *
+ * new S3({
+ *   credentials: createCredentialChain(fromEnv(init), fromIni(init)),
+ * });
+ * ```
+ *
+ * @param credentialProviders - one or more credential providers.
+ * @returns a single AwsCredentialIdentityProvider that calls the given
+ * providers in sequence until one succeeds or all fail.
+ */
+export declare const createCredentialChain: (...credentialProviders: AwsCredentialIdentityProvider[]) => AwsCredentialIdentityProvider & CustomCredentialChainOptions;

package/dist-types/index.d.ts

@@ -1,8 +1,9 @@
+export * from "./createCredentialChain";
 export * from "./fromCognitoIdentity";
 export * from "./fromCognitoIdentityPool";
 export * from "./fromContainerMetadata";
-export * from "./fromEnv";
 export { fromHttp, FromHttpOptions, HttpProviderCredentials } from "@aws-sdk/credential-provider-http";
+export * from "./fromEnv";
 export * from "./fromIni";
 export * from "./fromInstanceMetadata";
 export * from "./fromNodeProviderChain";

package/dist-types/ts3.4/createCredentialChain.d.ts

@@ -0,0 +1,9 @@
+import { AwsCredentialIdentityProvider } from "@smithy/types";
+export interface CustomCredentialChainOptions {
+  expireAfter(
+    milliseconds: number
+  ): AwsCredentialIdentityProvider & CustomCredentialChainOptions;
+}
+export declare const createCredentialChain: (
+  ...credentialProviders: AwsCredentialIdentityProvider[]
+) => AwsCredentialIdentityProvider & CustomCredentialChainOptions;

package/dist-types/ts3.4/index.d.ts

@@ -1,12 +1,13 @@
+export * from "./createCredentialChain";
 export * from "./fromCognitoIdentity";
 export * from "./fromCognitoIdentityPool";
 export * from "./fromContainerMetadata";
-export * from "./fromEnv";
 export {
   fromHttp,
   FromHttpOptions,
   HttpProviderCredentials,
 } from "@aws-sdk/credential-provider-http";
+export * from "./fromEnv";
 export * from "./fromIni";
 export * from "./fromInstanceMetadata";
 export * from "./fromNodeProviderChain";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-sdk/credential-providers",
-  "version": "3.629.0",
+  "version": "3.630.0",
   "description": "A collection of credential providers, without requiring service clients like STS, Cognito",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",