Error handling

The application throws nested errors, ranging from functional to technical. All errors extend SdsdkError.

Example of an invalid KAS credential error during encryption:

[KasError: Unable to wrap DEK.] {
  cause: [InternalError: HTTP Error 401: Unauthorized - {"code":401,"message":"Kas Encrypt route call failed. Please contact your administrator.","details":"2001026,2006003,1014001,2005006"}] {
    cause: undefined,
    code: 'http'
  },
  code: 'wrap_dek'
}

Possible errors

The Stormshield SDK exposes the following errors:

Error class name	Code	Description
UnwrapDekError		The DEK could not be unwrapped.
	unwrap_dek	The DEK could not be unwrapped.
KasError		An error happened with the KAS that holds the KEK.
	wrap_dek	The DEK could not be wrapped by the KAS.
	unwrap_dek_split	A split of the DEK could not be retrieved.
	unsupported_protocol	The requested protocol is not supported by the KAS.
	invalid_kas_response	The KAS responded, but the response format was unexpected.
	invalid_kas_type	The selected KAS type (remote, local) was not expected.
ConfigurationError		The configuration of Stormshield SDK instance is invalid.
	kas_list	The kasList is invalid.
	mapping	The mapping is invalid.
KasSelectionError		The resolution of the selection of one or several KASes in the KasList failed.
	no_kao_matches_default_kas	The provided ZTDF does not includes the default KAS in its keyAccess.
	no_kas_mapping_matches_data_attributes	The mapping of DataAttributes matched a value that is not present in the mapping configuration.
	kas_does_not_support_protocol	The selected KAS does not support the requested protocol.
	no_kas_matches_requested_protocol	No KAS in the Kaslist or in the resolved mapping selection supports the requested protocol.
AuthorizationError		The KAS Policy Decision Point (PDP) explicitely forbids the DEK decryption (ABAC mecanism).
	dek_unwrapping_forbidden_by_pdp	The KAS Policy Decision Point (PDP) explicitely forbids the decryption of the DEK.
IntegrityError		The integrity of the ZTDF could not be verified.
	invalid_assertions_integrity	The integrity of the assertions could not be verified. The ZTDF may have been manually modified.
	invalid_root_signature	The integrity of the data could not be verified. The ZTDF may have been manually modified.
ValidationError		A validation failed.
	invalid_ztdf	The ZTDF is invalid.
	invalid_user_input	Some user input is invalid.
	invalid	A validation failed.
CryptographicError		A local cryptographic operation failed.
	data_decryption	The decryption of data failed.
	data_encryption	The encryption of data failed.
	dek_encryption	The encryption of the DEK failed.
	dek_decryption	The decryption of the DEK failed.
	rewrap_keypair_generation	The rewrap keypair generation failed.
	sign	A signature operation failed.
	hash	A hash generation failed.
	verify	A signature or hash verification failed.
	unsupported_algorithm	The requested cryptographic algorithm is not supported.
	random_generator	A random generation failed.
	uuid_generator	A UUID generation failed.
	parse_pem	An attempt to parse PEM failed.
InternalError		Low level errors, generally not needed for user.
	json_canonicalization	The JSON canonicalization failed.
	unexpected	Something unexpected happened.
	parsing	A parsing operation failed.
	http	An outgoing HTTP request responded with not ok code.
	network	A network issue prevents communication. Check network connectivity.
	invalid_execution_environment	The javascript runtime did not provide necessary dependencies (fetch, crypto).

Get error in the chain by code

You can assign custom logic for errors:

• by using instanceof narrowing.
• by using the findCode method to find if any error in the chain has a code.

import { readFile } from 'node:fs/promises';
import { AuthorizationErrorCodes, ValidationError, SdsdkError, Ztdf } from 'sdsdk';

try {
  const ztdf = await readFile('encrypt-result.ztdf');
  const sdsdkZtdf = await Ztdf.fromZip(ztdf);
  const result = await sdsdkInstance.decrypt(sdsdkZtdf);
} catch (error) {
  console.log(error); // whole error chain

  if (error instanceof ValidationError) {
    // your custom logic for any root ValidationError
  }

  const sdkError = error as SdsdkError; // cast or narrow as SdsdkError
  if (sdkError.findCode(AuthorizationErrorCodes.DekUnwrappingForbiddenByPDP)) {
    // your custom logic for code dek_unwrapping_forbidden_by_pdp anywhere in the chain
  }
}