ibm-cloud-sdk-core 5.0.1 → 5.1.0

package/es/auth/token-managers/iam-request-based-token-manager.js

@@ -96,14 +96,6 @@ export class IamRequestBasedTokenManager extends JwtTokenManager {
             logger.warn(CLIENT_ID_SECRET_WARNING);
         }
     }
-    /**
-     * Returns the most recently stored refresh token.
-     *
-     * @returns the refresh token
-     */
-    getRefreshToken() {
-        return this.refreshToken;
-    }
     /**
      * Extend this method from the parent class to extract the refresh token from
      * the request and save it.
@@ -144,7 +136,11 @@ export class IamRequestBasedTokenManager extends JwtTokenManager {
                 rejectUnauthorized: !this.disableSslVerification,
             },
         };
-        return this.requestWrapperInstance.sendRequest(parameters);
+        logger.debug(`Invoking IAM get_token operation: ${parameters.options.url}`);
+        return this.requestWrapperInstance.sendRequest(parameters).then((response) => {
+            logger.debug('Returned from IAM get_token operation');
+            return response;
+        });
     }
     /**
      * Returns true iff the currently-cached IAM access token is expired.

package/es/auth/token-managers/iam-token-manager.d.ts

@@ -19,8 +19,8 @@ interface Options extends IamRequestOptions {
     apikey: string;
 }
 /**
- * The IAMTokenManager takes an api key and performs the necessary interactions with
- * the IAM token service to obtain and store a suitable bearer token. Additionally, the IAMTokenManager
+ * The IamTokenManager takes an api key and performs the necessary interactions with
+ * the IAM token service to obtain and store a suitable bearer token. Additionally, the IamTokenManager
  * will retrieve bearer tokens via basic auth using a supplied "clientId" and "clientSecret" pair.
  */
 export declare class IamTokenManager extends IamRequestBasedTokenManager {
@@ -46,5 +46,11 @@ export declare class IamTokenManager extends IamRequestBasedTokenManager {
      * @throws Error: the configuration options are not valid.
      */
     constructor(options: Options);
+    /**
+     * Returns the most recently stored refresh token.
+     *
+     * @returns the refresh token
+     */
+    getRefreshToken(): string;
 }
 export {};

package/es/auth/token-managers/iam-token-manager.js

@@ -17,8 +17,8 @@ import { validateInput } from '../utils/helpers';
 import { buildUserAgent } from '../../lib/build-user-agent';
 import { IamRequestBasedTokenManager } from './iam-request-based-token-manager';
 /**
- * The IAMTokenManager takes an api key and performs the necessary interactions with
- * the IAM token service to obtain and store a suitable bearer token. Additionally, the IAMTokenManager
+ * The IamTokenManager takes an api key and performs the necessary interactions with
+ * the IAM token service to obtain and store a suitable bearer token. Additionally, the IamTokenManager
  * will retrieve bearer tokens via basic auth using a supplied "clientId" and "clientSecret" pair.
  */
 export class IamTokenManager extends IamRequestBasedTokenManager {
@@ -52,4 +52,12 @@ export class IamTokenManager extends IamRequestBasedTokenManager {
         this.formData.response_type = 'cloud_iam';
         this.userAgent = buildUserAgent('iam-authenticator');
     }
+    /**
+     * Returns the most recently stored refresh token.
+     *
+     * @returns the refresh token
+     */
+    getRefreshToken() {
+        return this.refreshToken;
+    }
 }

package/es/auth/token-managers/index.d.ts

@@ -16,8 +16,8 @@
 /**
  * @module token-managers
  * The ibm-cloud-sdk-core module supports the following types of token authentication:
- *
- * Identity and Access Management (IAM)
+ * Identity and Access Management (IAM, grant type: apikey)
+ * Identity and Access Management (IAM, grant type: assume)
  * Cloud Pak for Data
  * Container (IKS, etc)
  * VPC Instance
@@ -28,6 +28,7 @@
  *
  * classes:
  *   IamTokenManager: Token Manager of IAM via apikey.
+ *   IamAssumeTokenManager: Token Manager of IAM via apikey and trusted profile.
  *   Cp4dTokenManager: Token Manager of CloudPak for data.
  *   ContainerTokenManager: Token manager of IAM via compute resource token.
  *   VpcInstanceTokenManager: Token manager of VPC Instance Metadata Service API tokens.
@@ -42,3 +43,4 @@ export { JwtTokenManager, JwtTokenManagerOptions } from './jwt-token-manager';
 export { TokenManager, TokenManagerOptions } from './token-manager';
 export { VpcInstanceTokenManager } from './vpc-instance-token-manager';
 export { McspTokenManager } from './mcsp-token-manager';
+export { IamAssumeTokenManager } from './iam-assume-token-manager';

package/es/auth/token-managers/index.js

@@ -16,8 +16,8 @@
 /**
  * @module token-managers
  * The ibm-cloud-sdk-core module supports the following types of token authentication:
- *
- * Identity and Access Management (IAM)
+ * Identity and Access Management (IAM, grant type: apikey)
+ * Identity and Access Management (IAM, grant type: assume)
  * Cloud Pak for Data
  * Container (IKS, etc)
  * VPC Instance
@@ -28,6 +28,7 @@
  *
  * classes:
  *   IamTokenManager: Token Manager of IAM via apikey.
+ *   IamAssumeTokenManager: Token Manager of IAM via apikey and trusted profile.
  *   Cp4dTokenManager: Token Manager of CloudPak for data.
  *   ContainerTokenManager: Token manager of IAM via compute resource token.
  *   VpcInstanceTokenManager: Token manager of VPC Instance Metadata Service API tokens.
@@ -42,3 +43,4 @@ export { JwtTokenManager } from './jwt-token-manager';
 export { TokenManager } from './token-manager';
 export { VpcInstanceTokenManager } from './vpc-instance-token-manager';
 export { McspTokenManager } from './mcsp-token-manager';
+export { IamAssumeTokenManager } from './iam-assume-token-manager';

package/es/auth/token-managers/mcsp-token-manager.js

@@ -17,6 +17,7 @@ import extend from 'extend';
 import { validateInput } from '../utils/helpers';
 import { buildUserAgent } from '../../lib/build-user-agent';
 import { JwtTokenManager } from './jwt-token-manager';
+import logger from '../../lib/logger';
 /**
  * This is the path associated with the operation used to obtain
  * an access token from the MCSP token service.
@@ -67,6 +68,10 @@ export class McspTokenManager extends JwtTokenManager {
                 rejectUnauthorized: !this.disableSslVerification,
             },
         };
-        return this.requestWrapperInstance.sendRequest(parameters);
+        logger.debug(`Invoking MCSP token service operation: ${parameters.options.url}`);
+        return this.requestWrapperInstance.sendRequest(parameters).then((response) => {
+            logger.debug('Returned from MCSP token service operation');
+            return response;
+        });
     }
 }

package/es/auth/token-managers/token-manager.js

@@ -42,11 +42,13 @@ export class TokenManager {
      */
     getToken() {
         if (!this.accessToken || this.isTokenExpired()) {
-            // 1. request a new token
+            // 1. Need a new token.
+            logger.debug('Performing synchronous token refresh');
             return this.pacedRequestToken().then(() => this.accessToken);
         }
-        // If refresh needed, kick one off
         if (this.tokenNeedsRefresh()) {
+            // 2. Need to refresh the current (valid) token.
+            logger.debug('Performing background asynchronous token fetch');
             this.requestToken().then((tokenResponse) => {
                 this.saveTokenInfo(tokenResponse);
             }, (err) => {
@@ -60,7 +62,9 @@ export class TokenManager {
                 logger.debug(err);
             });
         }
-        // 2. use valid, managed token
+        else {
+            logger.debug('Using cached access token');
+        }
         return Promise.resolve(this.accessToken);
     }
     /**

package/es/auth/token-managers/vpc-instance-token-manager.js

@@ -108,7 +108,10 @@ export class VpcInstanceTokenManager extends JwtTokenManager {
                 },
             };
             logger.debug(`Invoking VPC 'create_iam_token' operation: ${parameters.options.url}`);
-            return this.requestWrapperInstance.sendRequest(parameters);
+            return this.requestWrapperInstance.sendRequest(parameters).then((response) => {
+                logger.debug(`Returned from VPC 'create_iam_token' operation`);
+                return response;
+            });
         });
     }
     getInstanceIdentityToken() {

package/es/auth/utils/get-authenticator-from-environment.js

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Authenticator, BasicAuthenticator, BearerTokenAuthenticator, CloudPakForDataAuthenticator, IamAuthenticator, ContainerAuthenticator, NoAuthAuthenticator, VpcInstanceAuthenticator, McspAuthenticator, } from '../authenticators';
+import { Authenticator, BasicAuthenticator, BearerTokenAuthenticator, CloudPakForDataAuthenticator, IamAuthenticator, IamAssumeAuthenticator, ContainerAuthenticator, NoAuthAuthenticator, VpcInstanceAuthenticator, McspAuthenticator, } from '../authenticators';
 import { readExternalSources } from './read-external-sources';
 /**
  * Look for external configuration of authenticator.
@@ -78,6 +78,9 @@ export function getAuthenticatorFromEnvironment(serviceName) {
     else if (authType === Authenticator.AUTHTYPE_IAM.toLowerCase()) {
         authenticator = new IamAuthenticator(credentials);
     }
+    else if (authType === Authenticator.AUTHTYPE_IAM_ASSUME.toLowerCase()) {
+        authenticator = new IamAssumeAuthenticator(credentials);
+    }
     else if (authType === Authenticator.AUTHTYPE_CONTAINER.toLowerCase()) {
         authenticator = new ContainerAuthenticator(credentials);
     }

package/es/auth/utils/helpers.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2022.
+ * (C) Copyright IBM Corp. 2019, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,17 +43,6 @@ export declare function validateInput(options: any, requiredOptions: string[]):
  * @returns the current time in seconds.
  */
 export declare function getCurrentTime(): number;
-/**
- * Checks for only one of two elements being defined.
- * Returns true if a is defined and b is undefined,
- * or vice versa. Returns false if both are defined
- * or both are undefined.
- *
- * @param a - The first object
- * @param b - The second object
- * @returns true if and only if exactly one of a or b is defined
- */
-export declare function onlyOne(a: any, b: any): boolean;
 /**
  * Removes a given suffix if it exists.
  *
@@ -64,20 +53,26 @@ export declare function onlyOne(a: any, b: any): boolean;
  */
 export declare function removeSuffix(str: string, suffix: string): string;
 /**
- * Checks for at least one of two elements being defined.
+ * Checks that exactly one of the arguments provided is defined.
+ * Returns true if one argument is defined. Returns false if no
+ * argument are defined or if 2 or more are defined.
  *
- * @param a - the first object
- * @param b - the second object
- * @returns true if a or b is defined; false if both are undefined
+ * @param args - The spread of arguments to check
+ * @returns true if and only if exactly one argument is defined
  */
-export declare function atLeastOne(a: any, b: any): boolean;
+export declare function onlyOne(...args: any): boolean;
 /**
- * Verifies that both properties are not specified.
+ * Checks for at least one of the given elements being defined.
  *
- * @param a - The first object
- * @param b - The second object
+ * @param args - The spread of arguments to check
+ * @returns true if one or more are defined; false if all are undefined
+ */
+export declare function atLeastOne(...args: any): boolean;
+/**
+ * Verifies that no more than one of the given elements are defined.
+ * Returns true if one or none are defined, and false otherwise.
  *
- * @returns  false if a and b are both defined, true otherwise
-
+ * @param args - The spread of arguments to check
+ * @returns  false if more than one elements are defined, true otherwise
  */
-export declare function atMostOne(a: any, b: any): boolean;
+export declare function atMostOne(...args: any): boolean;

package/es/auth/utils/helpers.js

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2019, 2022.
+ * (C) Copyright IBM Corp. 2019, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -80,19 +80,6 @@ export function validateInput(options, requiredOptions) {
 export function getCurrentTime() {
     return Math.floor(Date.now() / 1000);
 }
-/**
- * Checks for only one of two elements being defined.
- * Returns true if a is defined and b is undefined,
- * or vice versa. Returns false if both are defined
- * or both are undefined.
- *
- * @param a - The first object
- * @param b - The second object
- * @returns true if and only if exactly one of a or b is defined
- */
-export function onlyOne(a, b) {
-    return Boolean((a && !b) || (b && !a));
-}
 /**
  * Removes a given suffix if it exists.
  *
@@ -108,24 +95,45 @@ export function removeSuffix(str, suffix) {
     return str;
 }
 /**
- * Checks for at least one of two elements being defined.
+ * Checks that exactly one of the arguments provided is defined.
+ * Returns true if one argument is defined. Returns false if no
+ * argument are defined or if 2 or more are defined.
  *
- * @param a - the first object
- * @param b - the second object
- * @returns true if a or b is defined; false if both are undefined
+ * @param args - The spread of arguments to check
+ * @returns true if and only if exactly one argument is defined
  */
-export function atLeastOne(a, b) {
-    return Boolean(a || b);
+export function onlyOne(...args) {
+    return countDefinedArgs(args) === 1;
 }
 /**
- * Verifies that both properties are not specified.
+ * Checks for at least one of the given elements being defined.
  *
- * @param a - The first object
- * @param b - The second object
+ * @param args - The spread of arguments to check
+ * @returns true if one or more are defined; false if all are undefined
+ */
+export function atLeastOne(...args) {
+    return countDefinedArgs(args) >= 1;
+}
+/**
+ * Verifies that no more than one of the given elements are defined.
+ * Returns true if one or none are defined, and false otherwise.
  *
- * @returns  false if a and b are both defined, true otherwise
-
+ * @param args - The spread of arguments to check
+ * @returns  false if more than one elements are defined, true otherwise
  */
-export function atMostOne(a, b) {
-    return Boolean(!(a && b));
+export function atMostOne(...args) {
+    return countDefinedArgs(args) <= 1;
+}
+/**
+ * Takes a list of anything (intended to be the arguments passed to one of the
+ * argument checking functions above) and returns how many elements in that
+ * list are not undefined.
+ */
+function countDefinedArgs(args) {
+    return args.reduce((total, arg) => {
+        if (arg) {
+            total += 1;
+        }
+        return total;
+    }, 0);
 }

package/es/auth/utils/read-external-sources.js

@@ -41,6 +41,7 @@ function getProperties(serviceName) {
     // 3. VCAP Services (Cloud Foundry)
     // only get properties from one source, return null if none found
     let properties = null;
+    logger.debug(`Retrieving config properties for service '${serviceName}'`);
     properties = filterPropertiesByServiceName(readCredentialsFile(), serviceName);
     if (isEmptyObject(properties)) {
         properties = filterPropertiesByServiceName(process.env, serviceName);
@@ -48,6 +49,7 @@ function getProperties(serviceName) {
     if (isEmptyObject(properties)) {
         properties = getPropertiesFromVCAP(serviceName);
     }
+    logger.debug(`Retrieved ${Object.keys(properties).length} properties`);
     return properties;
 }
 /**

package/es/lib/base-service.js

@@ -90,6 +90,7 @@ export class BaseService {
     setServiceUrl(url) {
         if (url) {
             this.baseOptions.serviceUrl = stripTrailingSlash(url);
+            logger.debug(`Set service URL: ${this.baseOptions.serviceUrl}`);
         }
     }
     /**
@@ -164,6 +165,7 @@ export class BaseService {
      * configuration.
      */
     configureService(serviceName) {
+        logger.debug(`Configuring BaseService instance with service name: ${serviceName}`);
         if (!serviceName) {
             const err = 'Error configuring service. Service name is required.';
             logger.error(err);

package/es/lib/private-helpers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * (C) Copyright IBM Corp. 2024.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Redacts secrets found in "input" so that the resulting string
+ * is suitable for debug logging.
+ * @param input - the string that potentially contains secrets
+ * @returns the input string with secrets replaced with "[redacted]"
+ */
+export declare function redactSecrets(input: string): string;

package/es/lib/private-helpers.js

@@ -0,0 +1,58 @@
+/**
+ * (C) Copyright IBM Corp. 2024.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Keywords that should be redacted.
+const redactedKeywords = [
+    'apikey',
+    'api_key',
+    'passcode',
+    'password',
+    'token',
+    'aadClientId',
+    'aadClientSecret',
+    'auth',
+    'auth_provider_x509_cert_url',
+    'auth_uri',
+    'client_email',
+    'client_id',
+    'client_x509_cert_url',
+    'key',
+    'project_id',
+    'secret',
+    'subscriptionId',
+    'tenantId',
+    'thumbprint',
+    'token_uri',
+];
+const redactedTokens = redactedKeywords.join('|');
+// Pre-compiled regular expressions used by redactSecrets().
+const reAuthHeader = new RegExp(`^(Authorization|X-Auth\\S*): .*$`, 'gim');
+const rePropertySetting = new RegExp(`(${redactedTokens})=[^&]*(&|$)`, 'gi');
+const reJsonField = new RegExp(`"([^"]*(${redactedTokens})[^"_]*)":\\s*"[^\\,]*"`, 'gi');
+// RedactSecrets() returns the input string with secrets redacted.
+/**
+ * Redacts secrets found in "input" so that the resulting string
+ * is suitable for debug logging.
+ * @param input - the string that potentially contains secrets
+ * @returns the input string with secrets replaced with "[redacted]"
+ */
+export function redactSecrets(input) {
+    const redacted = '[redacted]';
+    let redactedString = input;
+    redactedString = redactedString.replace(reAuthHeader, `$1: ${redacted}`);
+    redactedString = redactedString.replace(rePropertySetting, `$1=${redacted}$2`);
+    redactedString = redactedString.replace(reJsonField, `"$1":"${redacted}"`);
+    return redactedString;
+}

package/es/lib/request-wrapper.d.ts

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2014, 2023.
+ * (C) Copyright IBM Corp. 2014, 2024.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,6 +33,42 @@ export declare class RequestWrapper {
     private retryInterceptorId;
     private raxConfig;
     constructor(axiosOptions?: any);
+    /**
+     * Formats the specified Axios request for debug logging.
+     * @param request - the request to be logged
+     * @returns the string representation of the request
+     */
+    private formatAxiosRequest;
+    /**
+     * Formats the specified Axios response for debug logging.
+     * @param response - the response to be logged
+     * @returns the string representation of the response
+     */
+    private formatAxiosResponse;
+    /**
+     * Formats the specified Axios error for debug logging.
+     * @param error - the error to be logged
+     * @returns the string representation of the error
+     */
+    private formatAxiosError;
+    /**
+     * Formats 'headers' to be included in the debug output
+     * like this:
+     *    Accept: application/json
+     *    Content-Type: application/json
+     *    My-Header: my-value
+     *    ...
+     * @param headers - the headers associated with an Axios request or response
+     * @returns the formatted output to be included in the HTTP message traces
+     */
+    private formatAxiosHeaders;
+    /**
+     * Formats 'body' (either a string or object/array) to be included in the debug output
+     *
+     * @param body - a string, object or array that contains the request or response body
+     * @returns the formatted output to be included in the HTTP message traces
+     */
+    private formatAxiosBody;
     setCompressRequestData(setting: boolean): void;
     /**
      * Creates the request.
@@ -54,5 +90,11 @@ export declare class RequestWrapper {
     private static getRaxConfig;
     enableRetries(retryOptions?: RetryOptions): void;
     disableRetries(): void;
+    /**
+     * Returns true iff the previously-failed request contained in "error" should be retried.
+     * @param error - an AxiosError instance that contains a previously-failed request
+     * @returns true iff the request should be retried
+     */
+    private static retryPolicy;
     private gzipRequestBody;
 }