feat(api-rest): add rest default auth mode (#14525)

* feat: add rest auth mode

* feat: renamed parameter and added library option

* fix: change parameter name and type

* test: add test for local override global

* fix: syntax error

* fix: linting issue

* feat: add utils to resolve library options

Author: soberm

packages/api-rest/__tests__/apis/common/publicApis.test.ts

@@ -681,5 +681,113 @@ describe('public APIs', () => {
 				expect(result).toEqual({ retryable: false });
 			});
 		});
+
+		describe('defaultAuthMode option', () => {
+			it('should skip credential resolution when defaultAuthMode is "none"', async () => {
+				mockFetchAuthSession.mockClear();
+
+				await fn(mockAmplifyInstance, {
+					apiName: 'restApi1',
+					path: '/public',
+					options: {
+						defaultAuthMode: 'none',
+					},
+				}).response;
+
+				expect(mockFetchAuthSession).not.toHaveBeenCalled();
+				expect(mockUnauthenticatedHandler).toHaveBeenCalled();
+				expect(mockAuthenticatedHandler).not.toHaveBeenCalled();
+			});
+
+			it('should resolve credentials when defaultAuthMode is "iam"', async () => {
+				mockFetchAuthSession.mockResolvedValue({
+					credentials: {
+						accessKeyId: 'test-key',
+						secretAccessKey: 'test-secret',
+					},
+				});
+
+				await fn(mockAmplifyInstance, {
+					apiName: 'restApi1',
+					path: '/private',
+					options: {
+						defaultAuthMode: 'iam',
+					},
+				}).response;
+
+				expect(mockFetchAuthSession).toHaveBeenCalled();
+				expect(mockAuthenticatedHandler).toHaveBeenCalled();
+			});
+
+			it('should maintain default behavior when no defaultAuthMode specified', async () => {
+				mockFetchAuthSession.mockResolvedValue({
+					credentials: null,
+				});
+
+				await fn(mockAmplifyInstance, {
+					apiName: 'restApi1',
+					path: '/endpoint',
+				}).response;
+
+				expect(mockFetchAuthSession).toHaveBeenCalled();
+				expect(mockUnauthenticatedHandler).toHaveBeenCalled();
+			});
+
+			it('should use global defaultAuthMode configuration when no local defaultAuthMode is specified', async () => {
+				const mockAmplifyWithGlobalConfig = {
+					...mockAmplifyInstance,
+					libraryOptions: {
+						...mockAmplifyInstance.libraryOptions,
+						API: {
+							...mockAmplifyInstance.libraryOptions?.API,
+							REST: {
+								defaultAuthMode: 'none' as const,
+							},
+						},
+					},
+				} as any as AmplifyClassV6;
+
+				mockFetchAuthSession.mockClear();
+
+				await fn(mockAmplifyWithGlobalConfig, {
+					apiName: 'restApi1',
+					path: '/public',
+				}).response;
+
+				expect(mockFetchAuthSession).not.toHaveBeenCalled();
+				expect(mockUnauthenticatedHandler).toHaveBeenCalled();
+				expect(mockAuthenticatedHandler).not.toHaveBeenCalled();
+			});
+
+			it('should override global defaultAuthMode with local defaultAuthMode configuration', async () => {
+				const mockAmplifyWithGlobalConfig = {
+					...mockAmplifyInstance,
+					libraryOptions: {
+						...mockAmplifyInstance.libraryOptions,
+						API: {
+							...mockAmplifyInstance.libraryOptions?.API,
+							REST: {
+								defaultAuthMode: 'none' as const,
+							},
+						},
+					},
+				} as any as AmplifyClassV6;
+
+				mockFetchAuthSession.mockClear();
+				mockFetchAuthSession.mockResolvedValue({ credentials });
+
+				await fn(mockAmplifyWithGlobalConfig, {
+					apiName: 'restApi1',
+					path: '/private',
+					options: {
+						defaultAuthMode: 'iam',
+					},
+				}).response;
+
+				expect(mockFetchAuthSession).toHaveBeenCalled();
+				expect(mockAuthenticatedHandler).toHaveBeenCalled();
+				expect(mockUnauthenticatedHandler).not.toHaveBeenCalled();
+			});
+		});
 	});
 });

packages/api-rest/src/apis/common/transferHandler.ts

@@ -11,13 +11,15 @@ import {
 import {
 	AWSCredentials,
 	DocumentType,
+	RESTAuthMode,
 	RetryStrategy,
 } from '@aws-amplify/core/internals/utils';
 
 import {
 	logger,
 	parseRestApiServiceError,
 	parseSigningInfo,
+	resolveLibraryOptions,
 } from '../../utils';
 import { resolveHeaders } from '../../utils/resolveHeaders';
 import { RestApiResponse, SigningServiceInfo } from '../../types';
@@ -30,6 +32,7 @@ type HandlerOptions = Omit<HttpRequest, 'body' | 'headers'> & {
 	headers?: Headers;
 	withCredentials?: boolean;
 	retryStrategy?: RetryStrategy;
+	defaultAuthMode?: RESTAuthMode;
 };
 
 type RetryDecider = RetryOptions['retryDecider'];
@@ -75,19 +78,29 @@ export const transferHandler = async (
 		method,
 		body: resolvedBody,
 	};
+	const {
+		retryStrategy: libraryRetryStrategy,
+		defaultAuthMode: libraryDefaultAuthMode,
+	} = resolveLibraryOptions(amplify);
 	const baseOptions = {
 		retryDecider: getRetryDeciderFromStrategy(
-			retryStrategy ?? amplify?.libraryOptions?.API?.REST?.retryStrategy,
+			retryStrategy ?? libraryRetryStrategy,
 		),
 		computeDelay: jitteredBackoff,
 		withCrossDomainCredentials: withCredentials,
 		abortSignal,
 	};
 
-	const isIamAuthApplicable = iamAuthApplicable(request, signingServiceInfo);
+	const defaultAuthMode = options.defaultAuthMode ?? libraryDefaultAuthMode;
+
+	let credentials: AWSCredentials | null = null;
+	if (defaultAuthMode !== 'none') {
+		credentials = await resolveCredentials(amplify);
+	}
 
 	let response: RestApiResponse;
-	const credentials = await resolveCredentials(amplify);
+	const isIamAuthApplicable = iamAuthApplicable(request, signingServiceInfo);
+
 	if (isIamAuthApplicable && credentials) {
 		const signingInfoFromUrl = parseSigningInfo(url);
 		const signingService =

packages/api-rest/src/types/index.ts

@@ -1,6 +1,10 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { DocumentType, RetryStrategy } from '@aws-amplify/core/internals/utils';
+import {
+	DocumentType,
+	RESTAuthMode,
+	RetryStrategy,
+} from '@aws-amplify/core/internals/utils';
 
 export type GetInput = ApiInput<RestApiOptionsBase>;
 export type PostInput = ApiInput<RestApiOptionsBase>;
@@ -41,6 +45,7 @@ export interface RestApiOptionsBase {
 	 * @default ` { strategy: 'jittered-exponential-backoff' } `
 	 */
 	retryStrategy?: RetryStrategy;
+	defaultAuthMode?: RESTAuthMode;
 	/**
 	 * custom timeout in milliseconds.
 	 */

packages/api-rest/src/utils/index.ts

@@ -5,4 +5,5 @@ export { createCancellableOperation } from './createCancellableOperation';
 export { parseSigningInfo } from './parseSigningInfo';
 export { parseRestApiServiceError } from './serviceError';
 export { resolveApiUrl } from './resolveApiUrl';
+export { resolveLibraryOptions } from './resolveLibraryOptions';
 export { logger } from './logger';

packages/api-rest/src/utils/resolveLibraryOptions.ts

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AmplifyClassV6 } from '@aws-amplify/core';
+
+/**
+ * @internal
+ */
+export const resolveLibraryOptions = (amplify: AmplifyClassV6) => {
+	const retryStrategy = amplify.libraryOptions?.API?.REST?.retryStrategy;
+	const defaultAuthMode = amplify.libraryOptions?.API?.REST?.defaultAuthMode;
+
+	return { retryStrategy, defaultAuthMode };
+};

packages/core/src/libraryUtils.ts

@@ -48,6 +48,7 @@ export {
 	AssociationHasOne,
 	DocumentType,
 	GraphQLAuthMode,
+	RESTAuthMode,
 	ModelFieldType,
 	NonModelFieldType,
 	ModelIntrospectionSchema,

packages/core/src/singleton/API/types.ts

@@ -25,6 +25,10 @@ export interface LibraryAPIOptions {
 		 * @default ` { strategy: 'jittered-exponential-backoff' } `
 		 */
 		retryStrategy?: RetryStrategy;
+		/**
+		 * Default auth mode for REST API calls when no explicit auth is provided.
+		 */
+		defaultAuthMode?: RESTAuthMode;
 		/**
 		 * custom timeout in milliseconds configurable for given REST service, or/and method.
 		 */
@@ -142,6 +146,8 @@ export type GraphQLAuthMode =
 	| 'lambda'
 	| 'none';
 
+export type RESTAuthMode = 'none' | 'iam';
+
 /**
  * Type representing a plain JavaScript object that can be serialized to JSON.
  */