@aws-amplify/auth 6.7.1-unstable.ab33a03.0 → 6.8.0

package/src/client/utils/passkey/errors.ts

@@ -0,0 +1,214 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AmplifyError,
+	AmplifyErrorCode,
+	AmplifyErrorMap,
+	AmplifyErrorParams,
+	AssertionFunction,
+	createAssertionFunction,
+} from '@aws-amplify/core/internals/utils';
+
+export class PasskeyError extends AmplifyError {
+	constructor(params: AmplifyErrorParams) {
+		super(params);
+
+		// Hack for making the custom error class work when transpiled to es5
+		// TODO: Delete the following 2 lines after we change the build target to >= es2015
+		this.constructor = PasskeyError;
+		Object.setPrototypeOf(this, PasskeyError.prototype);
+	}
+}
+
+export enum PasskeyErrorCode {
+	// not supported
+	PasskeyNotSupported = 'PasskeyNotSupported',
+	// duplicate passkey
+	PasskeyAlreadyExists = 'PasskeyAlreadyExists',
+	// misconfigurations
+	InvalidPasskeyRegistrationOptions = 'InvalidPasskeyRegistrationOptions',
+	InvalidPasskeyAuthenticationOptions = 'InvalidPasskeyAuthenticationOptions',
+	RelyingPartyMismatch = 'RelyingPartyMismatch',
+	// failed credential creation / retrieval
+	PasskeyRegistrationFailed = 'PasskeyRegistrationFailed',
+	PasskeyRetrievalFailed = 'PasskeyRetrievalFailed',
+	// cancel / aborts
+	PasskeyRegistrationCanceled = 'PasskeyRegistrationCanceled',
+	PasskeyAuthenticationCanceled = 'PasskeyAuthenticationCanceled',
+	PasskeyOperationAborted = 'PasskeyOperationAborted',
+}
+
+const notSupportedRecoverySuggestion =
+	'Passkeys may not be supported on this device. Ensure your application is running in a secure context (HTTPS) and Web Authentication API is supported.';
+const abortOrCancelRecoverySuggestion =
+	'User may have canceled the ceremony or another interruption has occurred. Check underlying error for details.';
+const misconfigurationRecoverySuggestion =
+	'Ensure your user pool is configured to support the WEB_AUTHN as an authentication factor.';
+
+const passkeyErrorMap: AmplifyErrorMap<PasskeyErrorCode> = {
+	[PasskeyErrorCode.PasskeyNotSupported]: {
+		message: 'Passkeys may not be supported on this device.',
+		recoverySuggestion: notSupportedRecoverySuggestion,
+	},
+	[PasskeyErrorCode.InvalidPasskeyRegistrationOptions]: {
+		message: 'Invalid passkey registration options.',
+		recoverySuggestion: misconfigurationRecoverySuggestion,
+	},
+	[PasskeyErrorCode.InvalidPasskeyAuthenticationOptions]: {
+		message: 'Invalid passkey authentication options.',
+		recoverySuggestion: misconfigurationRecoverySuggestion,
+	},
+	[PasskeyErrorCode.PasskeyRegistrationFailed]: {
+		message: 'Device failed to create passkey.',
+		recoverySuggestion: notSupportedRecoverySuggestion,
+	},
+	[PasskeyErrorCode.PasskeyRetrievalFailed]: {
+		message: 'Device failed to retrieve passkey.',
+		recoverySuggestion:
+			'Passkeys may not be available on this device. Try an alternative authentication factor like PASSWORD, EMAIL_OTP, or SMS_OTP.',
+	},
+	[PasskeyErrorCode.PasskeyAlreadyExists]: {
+		message: 'Passkey already exists in authenticator.',
+		recoverySuggestion:
+			'Proceed with existing passkey or try again after deleting the credential.',
+	},
+	[PasskeyErrorCode.PasskeyRegistrationCanceled]: {
+		message: 'Passkey registration ceremony has been canceled.',
+		recoverySuggestion: abortOrCancelRecoverySuggestion,
+	},
+	[PasskeyErrorCode.PasskeyAuthenticationCanceled]: {
+		message: 'Passkey authentication ceremony has been canceled.',
+		recoverySuggestion: abortOrCancelRecoverySuggestion,
+	},
+	[PasskeyErrorCode.PasskeyOperationAborted]: {
+		message: 'Passkey operation has been aborted.',
+		recoverySuggestion: abortOrCancelRecoverySuggestion,
+	},
+	[PasskeyErrorCode.RelyingPartyMismatch]: {
+		message: 'Relying party does not match current domain.',
+		recoverySuggestion:
+			'Ensure relying party identifier matches current domain.',
+	},
+};
+
+export const assertPasskeyError: AssertionFunction<PasskeyErrorCode> =
+	createAssertionFunction(passkeyErrorMap, PasskeyError);
+
+/**
+ * Handle Passkey Authentication Errors
+ * https://w3c.github.io/webauthn/#sctn-get-request-exceptions
+ *
+ * @param err unknown
+ * @returns PasskeyError
+ */
+
+export const handlePasskeyAuthenticationError = (
+	err: unknown,
+): PasskeyError => {
+	if (err instanceof PasskeyError) {
+		return err;
+	}
+
+	if (err instanceof Error) {
+		if (err.name === 'NotAllowedError') {
+			const { message, recoverySuggestion } =
+				passkeyErrorMap[PasskeyErrorCode.PasskeyAuthenticationCanceled];
+
+			return new PasskeyError({
+				name: PasskeyErrorCode.PasskeyAuthenticationCanceled,
+				message,
+				recoverySuggestion,
+				underlyingError: err,
+			});
+		}
+	}
+
+	return handlePasskeyError(err);
+};
+
+/**
+ * Handle Passkey Registration Errors
+ * https://w3c.github.io/webauthn/#sctn-create-request-exceptions
+ *
+ * @param err unknown
+ * @returns PasskeyError
+ */
+export const handlePasskeyRegistrationError = (err: unknown): PasskeyError => {
+	if (err instanceof PasskeyError) {
+		return err;
+	}
+
+	if (err instanceof Error) {
+		// Duplicate Passkey
+		if (err.name === 'InvalidStateError') {
+			const { message, recoverySuggestion } =
+				passkeyErrorMap[PasskeyErrorCode.PasskeyAlreadyExists];
+
+			return new PasskeyError({
+				name: PasskeyErrorCode.PasskeyAlreadyExists,
+				message,
+				recoverySuggestion,
+				underlyingError: err,
+			});
+		}
+
+		// User Cancels Ceremony / Generic Catch All
+		if (err.name === 'NotAllowedError') {
+			const { message, recoverySuggestion } =
+				passkeyErrorMap[PasskeyErrorCode.PasskeyRegistrationCanceled];
+
+			return new PasskeyError({
+				name: PasskeyErrorCode.PasskeyRegistrationCanceled,
+				message,
+				recoverySuggestion,
+				underlyingError: err,
+			});
+		}
+	}
+
+	return handlePasskeyError(err);
+};
+
+/**
+ * Handles Overlapping Passkey Errors Between Registration & Authentication
+ * https://w3c.github.io/webauthn/#sctn-create-request-exceptions
+ * https://w3c.github.io/webauthn/#sctn-get-request-exceptions
+ *
+ * @param err unknown
+ * @returns PasskeyError
+ */
+const handlePasskeyError = (err: unknown): PasskeyError => {
+	if (err instanceof Error) {
+		// Passkey Operation Aborted
+		if (err.name === 'AbortError') {
+			const { message, recoverySuggestion } =
+				passkeyErrorMap[PasskeyErrorCode.PasskeyOperationAborted];
+
+			return new PasskeyError({
+				name: PasskeyErrorCode.PasskeyOperationAborted,
+				message,
+				recoverySuggestion,
+				underlyingError: err,
+			});
+		}
+		// Relying Party / Domain Mismatch
+		if (err.name === 'SecurityError') {
+			const { message, recoverySuggestion } =
+				passkeyErrorMap[PasskeyErrorCode.RelyingPartyMismatch];
+
+			return new PasskeyError({
+				name: PasskeyErrorCode.RelyingPartyMismatch,
+				message,
+				recoverySuggestion,
+				underlyingError: err,
+			});
+		}
+	}
+
+	return new PasskeyError({
+		name: AmplifyErrorCode.Unknown,
+		message: 'An unknown error has occurred.',
+		underlyingError: err,
+	});
+};

package/src/client/utils/passkey/getIsPasskeySupported.native.ts

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+
+export const getIsPasskeySupported = () => {
+	throw new PlatformNotSupportedError();
+};

package/src/client/utils/passkey/getIsPasskeySupported.ts

@@ -0,0 +1,18 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isBrowser } from '@aws-amplify/core/internals/utils';
+
+/**
+ * Determines if passkey is supported in current context
+ * Will return false if executed in non-secure context
+ * @returns boolean
+ */
+export const getIsPasskeySupported = (): boolean => {
+	return (
+		isBrowser() &&
+		window.isSecureContext &&
+		'credentials' in navigator &&
+		typeof window.PublicKeyCredential === 'function'
+	);
+};

package/src/client/utils/passkey/getPasskey.native.ts

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+
+export const getPasskey = async () => {
+	throw new PlatformNotSupportedError();
+};

package/src/client/utils/passkey/getPasskey.ts

@@ -0,0 +1,40 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	PasskeyErrorCode,
+	assertPasskeyError,
+	handlePasskeyAuthenticationError,
+} from './errors';
+import { getIsPasskeySupported } from './getIsPasskeySupported';
+import {
+	deserializeJsonToPkcGetOptions,
+	serializePkcWithAssertionToJson,
+} from './serde';
+import {
+	PasskeyGetOptionsJson,
+	assertCredentialIsPkcWithAuthenticatorAssertionResponse,
+} from './types';
+
+export const getPasskey = async (input: PasskeyGetOptionsJson) => {
+	try {
+		const isPasskeySupported = getIsPasskeySupported();
+
+		assertPasskeyError(
+			isPasskeySupported,
+			PasskeyErrorCode.PasskeyNotSupported,
+		);
+
+		const passkeyGetOptions = deserializeJsonToPkcGetOptions(input);
+
+		const credential = await navigator.credentials.get({
+			publicKey: passkeyGetOptions,
+		});
+
+		assertCredentialIsPkcWithAuthenticatorAssertionResponse(credential);
+
+		return serializePkcWithAssertionToJson(credential);
+	} catch (err: unknown) {
+		throw handlePasskeyAuthenticationError(err);
+	}
+};

package/src/client/utils/passkey/index.ts

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { registerPasskey } from './registerPasskey';
+export { getPasskey } from './getPasskey';

package/src/client/utils/passkey/registerPasskey.native.ts

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PlatformNotSupportedError } from '@aws-amplify/core/internals/utils';
+
+export const registerPasskey = async () => {
+	throw new PlatformNotSupportedError();
+};

package/src/client/utils/passkey/registerPasskey.ts

@@ -0,0 +1,48 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	PasskeyCreateOptionsJson,
+	PasskeyCreateResultJson,
+	assertCredentialIsPkcWithAuthenticatorAttestationResponse,
+} from './types';
+import {
+	deserializeJsonToPkcCreationOptions,
+	serializePkcWithAttestationToJson,
+} from './serde';
+import {
+	PasskeyErrorCode,
+	assertPasskeyError,
+	handlePasskeyRegistrationError,
+} from './errors';
+import { getIsPasskeySupported } from './getIsPasskeySupported';
+
+/**
+ * Registers a new passkey for user
+ * @param input - PasskeyCreateOptionsJson
+ * @returns serialized PasskeyCreateResult
+ */
+export const registerPasskey = async (
+	input: PasskeyCreateOptionsJson,
+): Promise<PasskeyCreateResultJson> => {
+	try {
+		const isPasskeySupported = getIsPasskeySupported();
+
+		assertPasskeyError(
+			isPasskeySupported,
+			PasskeyErrorCode.PasskeyNotSupported,
+		);
+
+		const passkeyCreationOptions = deserializeJsonToPkcCreationOptions(input);
+
+		const credential = await navigator.credentials.create({
+			publicKey: passkeyCreationOptions,
+		});
+
+		assertCredentialIsPkcWithAuthenticatorAttestationResponse(credential);
+
+		return serializePkcWithAttestationToJson(credential);
+	} catch (err) {
+		throw handlePasskeyRegistrationError(err);
+	}
+};

package/src/client/utils/passkey/serde.ts

@@ -0,0 +1,151 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	convertArrayBufferToBase64Url,
+	convertBase64UrlToArrayBuffer,
+} from '../../../foundation/convert';
+
+import {
+	PasskeyCreateOptionsJson,
+	PasskeyCreateResultJson,
+	PasskeyGetOptionsJson,
+	PasskeyGetResultJson,
+	PkcAssertionResponse,
+	PkcAttestationResponse,
+	PkcWithAuthenticatorAssertionResponse,
+	PkcWithAuthenticatorAttestationResponse,
+} from './types';
+
+/**
+ * Deserializes Public Key Credential Creation Options JSON
+ * @param input PasskeyCreateOptionsJson
+ * @returns PublicKeyCredentialCreationOptions
+ */
+export const deserializeJsonToPkcCreationOptions = (
+	input: PasskeyCreateOptionsJson,
+): PublicKeyCredentialCreationOptions => {
+	const userIdBuffer = convertBase64UrlToArrayBuffer(input.user.id);
+	const challengeBuffer = convertBase64UrlToArrayBuffer(input.challenge);
+	const excludeCredentialsWithBuffer = (input.excludeCredentials || []).map(
+		excludeCred => ({
+			...excludeCred,
+			id: convertBase64UrlToArrayBuffer(excludeCred.id),
+		}),
+	);
+
+	return {
+		...input,
+		excludeCredentials: excludeCredentialsWithBuffer,
+		challenge: challengeBuffer,
+		user: {
+			...input.user,
+			id: userIdBuffer,
+		},
+	};
+};
+
+/**
+ * Serializes a Public Key Credential With Attestation to JSON
+ * @param input PasskeyCreateResult
+ * @returns PasskeyCreateResultJson
+ */
+export const serializePkcWithAttestationToJson = (
+	input: PkcWithAuthenticatorAttestationResponse,
+): PasskeyCreateResultJson => {
+	const response: PkcAttestationResponse<string> = {
+		clientDataJSON: convertArrayBufferToBase64Url(
+			input.response.clientDataJSON,
+		),
+		attestationObject: convertArrayBufferToBase64Url(
+			input.response.attestationObject,
+		),
+		transports: input.response.getTransports(),
+		publicKeyAlgorithm: input.response.getPublicKeyAlgorithm(),
+		authenticatorData: convertArrayBufferToBase64Url(
+			input.response.getAuthenticatorData(),
+		),
+	};
+
+	const publicKey = input.response.getPublicKey();
+
+	if (publicKey) {
+		response.publicKey = convertArrayBufferToBase64Url(publicKey);
+	}
+
+	const resultJson: PasskeyCreateResultJson = {
+		type: input.type,
+		id: input.id,
+		rawId: convertArrayBufferToBase64Url(input.rawId),
+		clientExtensionResults: input.getClientExtensionResults(),
+		response,
+	};
+
+	if (input.authenticatorAttachment) {
+		resultJson.authenticatorAttachment = input.authenticatorAttachment;
+	}
+
+	return resultJson;
+};
+
+/**
+ * Deserializes Public Key Credential Get Options JSON
+ * @param input PasskeyGetOptionsJson
+ * @returns PublicKeyCredentialRequestOptions
+ */
+export const deserializeJsonToPkcGetOptions = (
+	input: PasskeyGetOptionsJson,
+): PublicKeyCredentialRequestOptions => {
+	const challengeBuffer = convertBase64UrlToArrayBuffer(input.challenge);
+	const allowedCredentialsWithBuffer = (input.allowCredentials || []).map(
+		allowedCred => ({
+			...allowedCred,
+			id: convertBase64UrlToArrayBuffer(allowedCred.id),
+		}),
+	);
+
+	return {
+		...input,
+		challenge: challengeBuffer,
+		allowCredentials: allowedCredentialsWithBuffer,
+	};
+};
+
+/**
+ * Serializes a Public Key Credential With Attestation to JSON
+ * @param input PasskeyGetResult
+ * @returns PasskeyGetResultJson
+ */
+export const serializePkcWithAssertionToJson = (
+	input: PkcWithAuthenticatorAssertionResponse,
+): PasskeyGetResultJson => {
+	const response: PkcAssertionResponse<string> = {
+		clientDataJSON: convertArrayBufferToBase64Url(
+			input.response.clientDataJSON,
+		),
+		authenticatorData: convertArrayBufferToBase64Url(
+			input.response.authenticatorData,
+		),
+		signature: convertArrayBufferToBase64Url(input.response.signature),
+	};
+
+	if (input.response.userHandle) {
+		response.userHandle = convertArrayBufferToBase64Url(
+			input.response.userHandle,
+		);
+	}
+
+	const resultJson: PasskeyGetResultJson = {
+		id: input.id,
+		rawId: convertArrayBufferToBase64Url(input.rawId),
+		type: input.type,
+		clientExtensionResults: input.getClientExtensionResults(),
+		response,
+	};
+
+	if (input.authenticatorAttachment) {
+		resultJson.authenticatorAttachment = input.authenticatorAttachment;
+	}
+
+	return resultJson;
+};

package/src/client/utils/passkey/types/index.ts

@@ -0,0 +1,61 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PasskeyErrorCode, assertPasskeyError } from '../errors';
+
+/**
+ * Passkey Create Types
+ */
+
+export {
+	PkcAttestationResponse,
+	PasskeyCreateOptionsJson,
+	PasskeyCreateResultJson,
+	assertValidCredentialCreationOptions,
+} from './shared';
+
+export type PkcWithAuthenticatorAttestationResponse = Omit<
+	PublicKeyCredential,
+	'response'
+> & {
+	response: AuthenticatorAttestationResponse;
+};
+
+export function assertCredentialIsPkcWithAuthenticatorAttestationResponse(
+	credential: any,
+): asserts credential is PkcWithAuthenticatorAttestationResponse {
+	assertPasskeyError(
+		credential &&
+			credential instanceof PublicKeyCredential &&
+			credential.response instanceof AuthenticatorAttestationResponse,
+		PasskeyErrorCode.PasskeyRegistrationFailed,
+	);
+}
+
+/**
+ * Passkey Get Types
+ */
+
+export {
+	PkcAssertionResponse,
+	PasskeyGetOptionsJson,
+	PasskeyGetResultJson,
+} from './shared';
+
+export type PkcWithAuthenticatorAssertionResponse = Omit<
+	PublicKeyCredential,
+	'response'
+> & {
+	response: AuthenticatorAssertionResponse;
+};
+
+export function assertCredentialIsPkcWithAuthenticatorAssertionResponse(
+	credential: any,
+): asserts credential is PkcWithAuthenticatorAssertionResponse {
+	assertPasskeyError(
+		credential &&
+			credential instanceof PublicKeyCredential &&
+			credential.response instanceof AuthenticatorAssertionResponse,
+		PasskeyErrorCode.PasskeyRetrievalFailed,
+	);
+}

package/src/client/utils/passkey/types/shared.ts

@@ -0,0 +1,131 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PasskeyErrorCode, assertPasskeyError } from '../errors';
+
+type PasskeyTransport = 'ble' | 'hybrid' | 'internal' | 'nfc' | 'usb';
+type UserVerificationRequirement = 'discouraged' | 'preferred' | 'required';
+type AttestationConveyancePreference =
+	| 'direct'
+	| 'enterprise'
+	| 'indirect'
+	| 'none';
+
+interface PkcDescriptor<T> {
+	type: 'public-key';
+	id: T;
+	transports?: PasskeyTransport[];
+}
+
+/**
+ * Passkey Create Types
+ */
+export interface PasskeyCreateOptionsJson {
+	challenge: string;
+	rp: {
+		id: string;
+		name: string;
+	};
+	user: {
+		id: string;
+		name: string;
+		displayName: string;
+	};
+	pubKeyCredParams: {
+		alg: number;
+		type: 'public-key';
+	}[];
+	timeout?: number;
+	excludeCredentials?: PkcDescriptor<string>[];
+	authenticatorSelection?: {
+		requireResidentKey: boolean;
+		residentKey: UserVerificationRequirement;
+		userVerification: UserVerificationRequirement;
+	};
+	attestation?: AttestationConveyancePreference;
+	extensions?: {
+		appid?: string;
+		appidExclude?: string;
+		credProps?: boolean;
+	};
+}
+
+export interface PkcAttestationResponse<T> {
+	clientDataJSON: T;
+	attestationObject: T;
+	transports: string[];
+	publicKey?: string;
+	publicKeyAlgorithm: number;
+	authenticatorData: T;
+}
+export interface PasskeyCreateResult {
+	id: string;
+	rawId: ArrayBuffer;
+	type: 'public-key';
+	response: PkcAttestationResponse<ArrayBuffer>;
+}
+
+export interface PasskeyCreateResultJson {
+	id: string;
+	rawId: string;
+	type: string;
+	clientExtensionResults: {
+		appId?: boolean;
+		credProps?: { rk?: boolean };
+		hmacCreateSecret?: boolean;
+	};
+	authenticatorAttachment?: string;
+	response: PkcAttestationResponse<string>;
+}
+
+export function assertValidCredentialCreationOptions(
+	credentialCreationOptions: any,
+): asserts credentialCreationOptions is PasskeyCreateOptionsJson {
+	assertPasskeyError(
+		[
+			!!credentialCreationOptions,
+			!!credentialCreationOptions?.challenge,
+			!!credentialCreationOptions?.user,
+			!!credentialCreationOptions?.rp,
+			!!credentialCreationOptions?.pubKeyCredParams,
+		].every(Boolean),
+		PasskeyErrorCode.InvalidPasskeyRegistrationOptions,
+	);
+}
+
+/**
+ * Passkey Get Types
+ */
+export interface PasskeyGetOptionsJson {
+	challenge: string;
+	rpId: string;
+	timeout: number;
+	allowCredentials: PkcDescriptor<string>[];
+	userVerification: UserVerificationRequirement;
+}
+
+export interface PkcAssertionResponse<T> {
+	authenticatorData: T;
+	clientDataJSON: T;
+	signature: T;
+	userHandle?: T;
+}
+
+export interface PasskeyGetResult {
+	id: string;
+	rawId: ArrayBuffer;
+	type: 'public-key';
+	response: PkcAssertionResponse<ArrayBuffer>;
+}
+export interface PasskeyGetResultJson {
+	id: string;
+	rawId: string;
+	type: string;
+	clientExtensionResults: {
+		appId?: boolean;
+		credProps?: { rk?: boolean };
+		hmacCreateSecret?: boolean;
+	};
+	authenticatorAttachment?: string;
+	response: PkcAssertionResponse<string>;
+}