Utils for Vereign Mini Product
Abstract
Utilities can be used in Browser and Node.JS environments.
The project is written with TypeScript. Import desired types in the code as needed.
import { StatusData } from "@vereign/light-utils
Installation
yarn add git+ssh://git@code.vereign.com:light/clients/utils.git
Development
Startup
git submodule init
git submodule update
yarn install
./generateProto.sh
yarn start
Testing
Some of the tests serving purely demonstration purpose and do not validate anything.
yarn test
-
NODE_ICU_DATA=node_modules/full-icu yarn test
if there are problems with the mime encoding
Local usage in external projects
- In the
utils
project directory callyarn link
ornpm link
- In the project which depends on
utils
callyarn link @vereign/light-utils
ornpm link @vereign/light-utils
Services and utilities
-
CryptoService
- servers cryptographic needs. Works based on WebCrypto (browser) and Node.JS Crypto, depending on the environment. -
MailParser
- utility used to parse MIME messages -
[DEPRECATED] MimeVerificationService
- used to verify plain and HTML parts of the MIME messages using the Rabin-Karp searching algorithm. Contains normalization strategies for GMail and Outlook MIME messages. -
CloudflareService
- performs interaction with Backblaze CDN. Contains utility methods to retrieve and parse statuses data. -
AeternityService
- performs interaction with Aeternity blockchain -
VerificatioService
- performs complex verification of the status data using Merkle Tree. Depends onAeternityService
andCloudflareService
. -
QrCodeDataService
- performs protobuffer encoding/decoding of the Qr Code Data -
StatusesService
- performs protobuffer encoding/decoding of the statuses data. - SigningService - encapsulates MIME signing and verification logic
Usage examples of some services provided in the corresponding __tests__
SigningService
Initialisation
import { SigningService } from "@vereign/light-utils";
const signingService = new SigningService();
/**
* [Optional]
* Define a custom DOM parsing function.
* By default it's using browser DOM parser.
*/
signingService.helpers.parseHtml = (htmlString) => {
const jsdom = new JSDOM(htmlString);
return jsdom.window.document;
};
/**
* [Optional]
* Define a custom SHA256 funcion.
* By default it's using WebCrypto or Node.JS Crypto API
* The function must properly handle bytes, base64 strings and utf8 strings
* base64 stirngs must be directly covnerted to bytes
* Refer to ICryptoService for further details
*/
signingService.helpers.cryptoService.SHA256 = async (value: string) => {
// returns hash base64 string
};
/**
* [Required]
* Define a custom RSA signing function.
*/
signingService.helpers.signRSAExternal = async (value: string) => {
// returns signature base64 string
};
/**
* [Optional]
* Define a function to verify RSA signature.
* Uses WebCrypto/Node.JS crypto by default
* Refer to ICryptoService for further details
*/
signingService.helpers.cryptoService.verifyRSASignature = async (
publicKeyPEM,
data,
signature
) => {
// returns true/false
};
MIME components signing
import { StatusesService } from "@vereign/light-utils";
const EMAIL_VENDORS = StatusesService.EMAIL_VENDORS;
const {
partsSignatures,
rabinFingerprints,
} = await signingService.signMimeComponents(
EMAIL_VENDORS.GMAIL,
senderHtml,
senderPlain,
senderAttachments
);
MIME components verification
import { StatusesService } from "@vereign/light-utils";
const EMAIL_VENDORS = StatusesService.EMAIL_VENDORS;
const {
htmlPartsSignatureValid,
plainPartsSignatureValid,
pseudoPlainPartsSignatureValid,
attachmentsPartsSignatureValid,
severityLevel,
statusMessage,
} = await signingService.verifyMimeComponents(
publicKeyBase64,
EMAIL_VENDORS.GMAIL,
receiverHtml,
receiverPlain,
receiverAttachments,
partsSignatures,
rabinFingerprints
);