@aws-amplify/core 5.2.1-unstable.eca5078.2 → 5.3.0

package/src/clients/middleware/signing/signer/signatureV4/utils/dataHashHelpers.ts

@@ -0,0 +1,42 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// TODO: V6 update to different crypto dependency?
+import { Sha256 } from '@aws-crypto/sha256-js';
+import { SourceData } from '@aws-sdk/types';
+import { toHex } from '@aws-sdk/util-hex-encoding';
+
+/**
+ * Returns the hashed data a `Uint8Array`.
+ *
+ * @param key `SourceData` to be used as hashing key.
+ * @param data Hashable `SourceData`.
+ * @returns `Uint8Array` created from the data as input to a hash function.
+ */
+export const getHashedData = (
+	key: SourceData | null,
+	data: SourceData
+): Uint8Array => {
+	const sha256 = new Sha256(key);
+	sha256.update(data);
+	// TODO: V6 flip to async digest
+	const hashedData = sha256.digestSync();
+	return hashedData;
+};
+
+/**
+ * Returns the hashed data as a hex string.
+ *
+ * @param key `SourceData` to be used as hashing key.
+ * @param data Hashable `SourceData`.
+ * @returns String using lowercase hexadecimal characters created from the data as input to a hash function.
+ *
+ * @internal
+ */
+export const getHashedDataAsHex = (
+	key: SourceData | null,
+	data: SourceData
+): string => {
+	const hashedData = getHashedData(key, data);
+	return toHex(hashedData);
+};

package/src/clients/middleware/signing/signer/signatureV4/utils/getCanonicalHeaders.ts

@@ -0,0 +1,25 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpRequest } from '../../../../../types';
+
+/**
+ * Returns canonical headers.
+ *
+ * @param headers Headers from the request.
+ * @returns Request headers that will be signed, and their values, separated by newline characters. Header names must
+ * use lowercase characters, must appear in alphabetical order, and must be followed by a colon (:). For the values,
+ * trim any leading or trailing spaces, convert sequential spaces to a single space, and separate the values
+ * for a multi-value header using commas.
+ *
+ * @internal
+ */
+export const getCanonicalHeaders = (headers: HttpRequest['headers']): string =>
+	Object.entries(headers)
+		.map(([key, value]) => ({
+			key: key.toLowerCase(),
+			value: value?.trim().replace(/\s+/g, ' ') ?? '',
+		}))
+		.sort((a, b) => (a.key < b.key ? -1 : 1))
+		.map(entry => `${entry.key}:${entry.value}\n`)
+		.join('');

package/src/clients/middleware/signing/signer/signatureV4/utils/getCanonicalQueryString.ts

@@ -0,0 +1,32 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Returns a canonical query string.
+ *
+ * @param searchParams `searchParams` from the request url.
+ * @returns URL-encoded query string parameters, separated by ampersands (&). Percent-encode reserved characters,
+ * including the space character. Encode names and values separately. If there are empty parameters, append the equals
+ * sign to the parameter name before encoding. After encoding, sort the parameters alphabetically by key name. If there
+ * is no query string, use an empty string ("").
+ *
+ * @internal
+ */
+export const getCanonicalQueryString = (
+	searchParams: URLSearchParams
+): string =>
+	Array.from(searchParams)
+		.sort(([keyA, valA], [keyB, valB]) => {
+			if (keyA === keyB) {
+				return valA < valB ? -1 : 1;
+			}
+			return keyA < keyB ? -1 : 1;
+		})
+		.map(([key, val]) => `${escapeUri(key)}=${escapeUri(val)}`)
+		.join('&');
+
+const escapeUri = (uri: string): string =>
+	encodeURIComponent(uri).replace(/[!'()*]/g, hexEncode);
+
+const hexEncode = (c: string) =>
+	`%${c.charCodeAt(0).toString(16).toUpperCase()}`;

package/src/clients/middleware/signing/signer/signatureV4/utils/getCanonicalRequest.ts

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpRequest } from '../../../../../types';
+import { getCanonicalHeaders } from './getCanonicalHeaders';
+import { getCanonicalQueryString } from './getCanonicalQueryString';
+import { getCanonicalUri } from './getCanonicalUri';
+import { getHashedPayload } from './getHashedPayload';
+import { getSignedHeaders } from './getSignedHeaders';
+
+/**
+ * Returns a canonical request.
+ *
+ * @param request `HttpRequest` from which to create the canonical request from.
+ * @returns String created by by concatenating the following strings, separated by newline characters:
+ * - HTTPMethod
+ * - CanonicalUri
+ * - CanonicalQueryString
+ * - CanonicalHeaders
+ * - SignedHeaders
+ * - HashedPayload
+ *
+ * @internal
+ */
+export const getCanonicalRequest = ({
+	body,
+	headers,
+	method,
+	url,
+}: HttpRequest): string =>
+	[
+		method,
+		getCanonicalUri(url.pathname),
+		getCanonicalQueryString(url.searchParams),
+		getCanonicalHeaders(headers),
+		getSignedHeaders(headers),
+		getHashedPayload(body),
+	].join('\n');

package/src/clients/middleware/signing/signer/signatureV4/utils/getCanonicalUri.ts

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Returns a canonical uri.
+ *
+ * @param pathname `pathname` from request url.
+ * @returns URI-encoded version of the absolute path component URL (everything between the host and the question mark
+ * character (?) that starts the query string parameters). If the absolute path is empty, a forward slash character (/).
+ *
+ * @internal
+ */
+export const getCanonicalUri = (pathname: string): string =>
+	pathname ? encodeURIComponent(pathname).replace(/%2F/g, '/') : '/';

package/src/clients/middleware/signing/signer/signatureV4/utils/getCredentialScope.ts

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { KEY_TYPE_IDENTIFIER } from '../constants';
+
+/**
+ * Returns the credential scope which restricts the resulting signature to the specified region and service.
+ *
+ * @param date Current date in the format 'YYYYMMDD'.
+ * @param region AWS region in which the service resides.
+ * @param service Service to which the signed request is being sent.
+ *
+ * @returns  A string representing the credential scope with format 'YYYYMMDD/region/service/aws4_request'.
+ *
+ * @internal
+ */
+export const getCredentialScope = (
+	date: string,
+	region: string,
+	service: string
+): string => `${date}/${region}/${service}/${KEY_TYPE_IDENTIFIER}`;

package/src/clients/middleware/signing/signer/signatureV4/utils/getFormattedDates.ts

@@ -0,0 +1,22 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { FormattedDates } from '../types/signer';
+
+/**
+ * Returns expected date strings to be used in signing.
+ *
+ * @param date JavaScript `Date` object.
+ * @returns `FormattedDates` object containing the following:
+ * - longDate: A date string in 'YYYYMMDDThhmmssZ' format
+ * - shortDate: A date string in 'YYYYMMDD' format
+ *
+ * @internal
+ */
+export const getFormattedDates = (date: Date): FormattedDates => {
+	const longDate = date.toISOString().replace(/[:\-]|\.\d{3}/g, '');
+	return {
+		longDate,
+		shortDate: longDate.slice(0, 8),
+	};
+};

package/src/clients/middleware/signing/signer/signatureV4/utils/getHashedPayload.ts

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { SourceData } from '@aws-sdk/types';
+import { HttpRequest } from '../../../../../types';
+import { EMPTY_HASH, UNSIGNED_PAYLOAD } from '../constants';
+import { getHashedDataAsHex } from './dataHashHelpers';
+
+/**
+ * Returns the hashed payload.
+ *
+ * @param body `body` (payload) from the request.
+ * @returns String created using the payload in the body of the HTTP request as input to a hash function. This string
+ * uses lowercase hexadecimal characters. If the payload is empty, return precalculated result of an empty hash.
+ *
+ * @internal
+ */
+export const getHashedPayload = (body: HttpRequest['body']): string => {
+	// return precalculated empty hash if body is undefined or null
+	if (body == null) {
+		return EMPTY_HASH;
+	}
+
+	if (isSourceData(body)) {
+		const hashedData = getHashedDataAsHex(null, body);
+		return hashedData;
+	}
+
+	// Defined body is not signable. Return unsigned payload which may or may not be accepted by the service.
+	return UNSIGNED_PAYLOAD;
+};
+
+const isSourceData = (body: HttpRequest['body']): body is SourceData =>
+	typeof body === 'string' || ArrayBuffer.isView(body) || isArrayBuffer(body);
+
+const isArrayBuffer = (arg: any): arg is ArrayBuffer =>
+	(typeof ArrayBuffer === 'function' && arg instanceof ArrayBuffer) ||
+	Object.prototype.toString.call(arg) === '[object ArrayBuffer]';

package/src/clients/middleware/signing/signer/signatureV4/utils/getSignature.ts

@@ -0,0 +1,52 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpRequest } from '../../../../../types';
+import { SigningValues } from '../types/signer';
+import { getHashedDataAsHex } from './dataHashHelpers';
+import { getCanonicalRequest } from './getCanonicalRequest';
+import { getSigningKey } from './getSigningKey';
+import { getStringToSign } from './getStringToSign';
+
+/**
+ * Calculates and returns an AWS API Signature.
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html
+ *
+ * @param request `HttpRequest` to be signed.
+ * @param signRequestOptions `SignRequestOptions` object containing values used to construct the signature.
+ * @returns AWS API Signature to sign a request or url with.
+ *
+ * @internal
+ */
+export const getSignature = (
+	request: HttpRequest,
+	{
+		credentialScope,
+		longDate,
+		secretAccessKey,
+		shortDate,
+		signingRegion,
+		signingService,
+	}: SigningValues
+): string => {
+	// step 1: create a canonical request
+	const canonicalRequest = getCanonicalRequest(request);
+
+	// step 2: create a hash of the canonical request
+	const hashedRequest = getHashedDataAsHex(null, canonicalRequest);
+
+	// step 3: create a string to sign
+	const stringToSign = getStringToSign(
+		longDate,
+		credentialScope,
+		hashedRequest
+	);
+
+	// step 4: calculate the signature
+	const signature = getHashedDataAsHex(
+		getSigningKey(secretAccessKey, shortDate, signingRegion, signingService),
+		stringToSign
+	);
+
+	return signature;
+};

package/src/clients/middleware/signing/signer/signatureV4/utils/getSignedHeaders.ts

@@ -0,0 +1,19 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { HttpRequest } from '../../../../../types';
+
+/**
+ * Returns signed headers.
+ *
+ * @param headers `headers` from the request.
+ * @returns List of headers included in canonical headers, separated by semicolons (;). This indicates which headers
+ * are part of the signing process. Header names must use lowercase characters and must appear in alphabetical order.
+ *
+ * @internal
+ */
+export const getSignedHeaders = (headers: HttpRequest['headers']): string =>
+	Object.keys(headers)
+		.map(key => key.toLowerCase())
+		.sort()
+		.join(';');

package/src/clients/middleware/signing/signer/signatureV4/utils/getSigningKey.ts

@@ -0,0 +1,31 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { KEY_TYPE_IDENTIFIER, SIGNATURE_IDENTIFIER } from '../constants';
+import { getHashedData } from './dataHashHelpers';
+
+/**
+ * Returns a signing key to be used for signing requests.
+ *
+ * @param secretAccessKey AWS secret access key from credentials.
+ * @param date Current date in the format 'YYYYMMDD'.
+ * @param region AWS region in which the service resides.
+ * @param service Service to which the signed request is being sent.
+ *
+ * @returns `Uint8Array` calculated from its composite parts.
+ *
+ * @internal
+ */
+export const getSigningKey = (
+	secretAccessKey: string,
+	date: string,
+	region: string,
+	service: string
+): Uint8Array => {
+	const key = `${SIGNATURE_IDENTIFIER}${secretAccessKey}`;
+	const dateKey = getHashedData(key, date);
+	const regionKey = getHashedData(dateKey, region);
+	const serviceKey = getHashedData(regionKey, service);
+	const signingKey = getHashedData(serviceKey, KEY_TYPE_IDENTIFIER);
+	return signingKey;
+};

package/src/clients/middleware/signing/signer/signatureV4/utils/getSigningValues.ts

@@ -0,0 +1,43 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { SignRequestOptions } from '../types';
+import { SigningValues } from '../types/signer';
+import { getCredentialScope } from './getCredentialScope';
+import { getFormattedDates } from './getFormattedDates';
+
+/**
+ * Extracts common values used for signing both requests and urls.
+ *
+ * @param options `SignRequestOptions` object containing values used to construct the signature.
+ * @returns Common `SigningValues` used for signing.
+ *
+ * @internal
+ */
+export const getSigningValues = ({
+	credentials,
+	signingDate = new Date(),
+	signingRegion,
+	signingService,
+}: SignRequestOptions): SigningValues => {
+	// get properties from credentials
+	const { accessKeyId, secretAccessKey, sessionToken } = credentials;
+	// get formatted dates for signing
+	const { longDate, shortDate } = getFormattedDates(signingDate);
+	// copy header and set signing properties
+	const credentialScope = getCredentialScope(
+		shortDate,
+		signingRegion,
+		signingService
+	);
+	return {
+		accessKeyId,
+		credentialScope,
+		longDate,
+		secretAccessKey,
+		sessionToken,
+		shortDate,
+		signingRegion,
+		signingService,
+	};
+};

package/src/clients/middleware/signing/signer/signatureV4/utils/getStringToSign.ts

@@ -0,0 +1,28 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { SHA256_ALGORITHM_IDENTIFIER } from '../constants';
+
+/**
+ * Returns a string to be signed.
+ *
+ * @param date Current date in the format 'YYYYMMDDThhmmssZ'.
+ * @param credentialScope String representing the credential scope with format 'YYYYMMDD/region/service/aws4_request'.
+ * @param hashedRequest Hashed canonical request.
+ *
+ * @returns A string created by by concatenating the following strings, separated by newline characters:
+ * - Algorithm
+ * - RequestDateTime
+ * - CredentialScope
+ * - HashedCanonicalRequest
+ *
+ * @internal
+ */
+export const getStringToSign = (
+	date: string,
+	credentialScope: string,
+	hashedRequest: string
+): string =>
+	[SHA256_ALGORITHM_IDENTIFIER, date, credentialScope, hashedRequest].join(
+		'\n'
+	);

package/src/clients/types/aws.ts

@@ -0,0 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export type { Credentials } from '@aws-sdk/types';
+
+export type SourceData = string | ArrayBuffer | ArrayBufferView;

package/src/clients/types/core.ts

@@ -0,0 +1,17 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * General None HTTP-specific request interface
+ */
+export interface Request {
+	url: URL;
+	body?: unknown;
+}
+
+export interface Response {
+	body: unknown;
+}
+export interface Endpoint {
+	url: URL;
+}

package/src/clients/types/http.ts

@@ -0,0 +1,33 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Request, Response } from './core';
+
+/**
+ * Use basic Record interface to workaround fetch Header class not available in Node.js
+ * The header names must be lowercased.
+ * TODO: use LowerCase<string> intrinsic when we can support typescript 4.0
+ */
+export type Headers = Record<string, string>;
+
+export interface HttpRequest extends Request {
+	method: string;
+	headers: Headers;
+	body?: BodyInit;
+}
+
+/**
+ * Reduce the API surface of Fetch API's Body mixin to only the methods we need.
+ * In React Native, body.arrayBuffer() is not supported.
+ * body.formData() is not supported for now.
+ */
+export type ResponseBodyMixin = Pick<Body, 'blob' | 'json' | 'text'>;
+
+export interface HttpResponse extends Response {
+	body: (ResponseBodyMixin & ReadableStream) | null;
+	statusCode: number;
+	/**
+	 * @see {@link HttpRequest.headers}
+	 */
+	headers: Headers;
+}

package/src/clients/types/index.ts

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { Headers, HttpRequest, HttpResponse } from './http';
+export { Credentials } from './aws';