@raytio/core

@raytio/core is a collection of low-level functions for using the Raytio API. It works in both the browser and a nodejs environment, although nodejs requires several polyfills (see below).

Usage no npm install needed!

<script type="module">
  import raytioCore from 'https://cdn.skypack.dev/@raytio/core';
</script>

README

@raytio/core

@raytio/core is a collection of low-level functions for using the Raytio API. It works in both the browser and a nodejs environment, although nodejs requires several polyfills (see below).

For a high-level and easy-to-use API, consider using @raytio/decrypt-helper.

Usage in nodejs

Nodejs does not support fetch, WebCrypto, or atob/btoa, so these will need to be polyfilled. Older versions of nodejs (<14.0.0) also do not support TextEncoder or Intl.DateTimeFormat.

If you use the high-level @raytio/decrypt-helper module, you don't need to worry about this.

If you wish to use @raytio/core directly, an example of configuring polyfills for nodejs is availble here

API

Table of contents

Type aliases

Functions

Type aliases

SafeHarbourObj

Ƭ SafeHarbourObj: Partial<Record<SafeHarbourCode, string[]>>

an object listing the xIds for each SafeHarbourCode

SafeHarbourResult

Ƭ SafeHarbourResult: Object

the response from calcSafeHarbourScore

Type declaration

Name Type
flags SafeHarbourObj
isSafe boolean

Functions

calcSafeHarbourScore

▸ Const calcSafeHarbourScore(data): Promise<SafeHarbourResult>

The Safe Harbour Score indidicates whether a person's identity has been verified to the extent requried for Safe Harbour Compliance. This requires multiple verifications from different sources. For information, refer to the Raytio Documentation.

Parameters

Name Type
data Object
data.person ProfileObject<Json>
data.profileObjects ProfileObject<Json>[]
data.realVers RealVer[]
data.getSchema (schemaName: string) => Promise<Schema>

Returns

Promise<SafeHarbourResult>

calculateScore

▸ calculateScore(ruleConfig, ruleInput): ScoreResult

the main function to calculate a score and category. Might throw an error.

Parameters

Name Type
ruleConfig ScoreConfig
ruleInput RuleData

Returns

ScoreResult

checkJsonSignature

▸ Const checkJsonSignature(data, signature): Promise<boolean>

checks that a json object was signed by the provided signature. Unless you're dealing with bundled verifications, you should use getOwnRealVerifications or getSomeoneElsesRealVerifications instead.

Parameters

Name Type
data unknown
signature string

Returns

Promise<boolean>

cleanInstance

▸ cleanInstance(instance): Instance

The API response from share/v2/access_application/instance/:iId returns a complicated hashed_n_id format, so you need to clean up the API response using this function as soon as possible.

We relace hashed_n_ids with a string HASHED::{NId}::{AId}

Parameters

Name Type
instance Instance

Returns

Instance

convertInstanceToRuleInput

▸ Const convertInstanceToRuleInput(instance, realVers, getSchema): Promise<RuleData>

Parameters

Name Type
instance Instance
realVers RealVer[]
getSchema (schemaName: string) => Promise<Schema>

Returns

Promise<RuleData>

createAA

▸ createAA(__namedParameters): Promise<AA>

Creates an Access Application and associated public+private keys.

The user must be part of an organization, and you need to include the orgId.

You must also supply an apiToken and an instance of the maxcryptor for that user, as well as the userDoc data which is stored in the user's cognito attributes.

Parameters

Name Type
__namedParameters Object
__namedParameters.apiToken string
__namedParameters.apiUrl string
__namedParameters.application Omit<AA, "a_id">
__namedParameters.maxcryptor DataEncryptorI
__namedParameters.userDoc UserDoc

Returns

Promise<AA>

decryptSharedData

▸ Const decryptSharedData(__namedParameters): Promise<Object>

Decrypts any encrypted properties included in the supplied instanceData. If nothing is encrypted the supplied instanceData is returned.

It will reject if there are keys missing for any encrypted properties, or if the encrypted data is invalid. If you don't want it to reject, you can supply a onCorruptedData function which returns a value to use instead.

Parameters

Name Type
__namedParameters Object
__namedParameters.apiToken string
__namedParameters.apiUrl string
__namedParameters.instanceData Instance
__namedParameters.maxcryptor DataEncryptorI
__namedParameters.onCorruptedData? (fieldName: string, fieldValue: Encrypted<string>, error: Error) => any

Returns

Promise<Object>

a copy of instanceData with all properties decrypted.

findSchemaLabel

▸ Const findSchemaLabel(labels): undefined | string

Finds the label (on a profile object) which is the schema name

Parameters

Name Type
labels undefined | string[]

Returns

undefined | string

fromCognitoAttributes

▸ Const fromCognitoAttributes(attributes): UserDoc

This function converts Cognito's userAttributes into a maxcryptor UserDoc. The userAttributes come from const attributes = await Auth.userAttributes(user)

Parameters

Name Type
attributes ICognitoUserAttributeData[]

Returns

UserDoc

getAADecryptor

▸ getAADecryptor(__namedParameters): Promise<Object>

Fetchs the public and private keys for an Access Application, then initializes the Maxcryptor's ApplicationEncryptor.

Parameters

Name Type
__namedParameters Arg

Returns

Promise<Object>

an ApplicationEncryptor and the public key of the Access Application

getOwnRealVerifications

▸ Const getOwnRealVerifications(__namedParameters): Promise<RealVer[]>

Given a list of verifications and decrypted profile objects, this function locally verifies the credibility of the signatures in the verifications.

This function does NOT call the API, except to fetch the public key.

Parameters

Name Type
__namedParameters Object
__namedParameters.profileObjects ProfileObject<Json>[]
__namedParameters.userId UId
__namedParameters.verifications Verification<false>[]

Returns

Promise<RealVer[]>

a list of authentic RealVer

getPOVerification

▸ getPOVerification(__namedParameters): Object

Determines the verification status of a profile object, and its individual fields.

Parameters

Name Type
__namedParameters Object
__namedParameters.PO ProfileObject<Json> | ProfileObjectForUpload<Json>
__namedParameters.realVers RealVer[]
__namedParameters.schema Schema

Returns

Object

Name Type
details Object
details.sourceNId? NId
details.verifiers VerificationProvider[]
fieldVerifications Record<string, FieldVerification>
status POVerification

getSomeoneElsesRealVerifications

▸ Const getSomeoneElsesRealVerifications(__namedParameters): Promise<RealVer[]>

Given a list of verifications and decrypted profile objects, this function calls the Raytio API to verify the credibility of these verifications, returning only valid verifications.

❗ prefer getOwnRealVerifications if the data to be verified belongs to the current user.

Parameters

Name Type
__namedParameters Props

Returns

Promise<RealVer[]>

a list of fileNames/values that are verified.

hashPassword

▸ hashPassword(password): Promise<string>

AWS Cognito never gets the raw password. We send them a hashed verison using PBKDF2 with SHA-256 and 10,000 iterations.

Parameters

Name Type Description
password string The raw password

Returns

Promise<string>

Promise resolving to the hashed password

isConditionMet

▸ Const isConditionMet(condition, formValues): boolean

Checks all other form values in case any have a trigger value that makes this field requirted.

Parameters

Name Type
condition Record<string, ConditionValue[]>
formValues Record<string, unknown>

Returns

boolean

isEncrypted

▸ Const isEncrypted(value): value is Encrypted<string>

Determines where the input is an encrypted Raytio object

Parameters

Name Type Description
value unknown anything

Returns

value is Encrypted<string>

true or false depending on whether the input is an encrypted Raytio object

isEncryptedFile

▸ Const isEncryptedFile(value): value is Encrypted<string>

Determines where the input is an encrypted Raytio file

Parameters

Name Type Description
value unknown anything

Returns

value is Encrypted<string>

true or false depending on whether the input is an encrypted Raytio file

someEncrypted

▸ Const someEncrypted<T, K>(...args): number

Given a profile object's properties, returns the number of properties that are encryted.

Type parameters

Name Type
T extends object
K extends string | number | symbol

Parameters

Name Type
...args [obj: T]

Returns

number

toCognitoAttributes

▸ Const toCognitoAttributes(userDoc): Object

Given a UserDoc from the maxcryptor, this returns an object which you can provide to Auth.updateUserAttributes(). It is an object of stringified Json.

Parameters

Name Type
userDoc UserDoc

Returns

Object