@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
- calcSafeHarbourScore
- calculateScore
- checkJsonSignature
- convertInstanceToRuleInput
- convertServerRelationship
- createAA
- createHashedNId
- decryptSharedData
- evaluateRule
- expandSchema
- findSchemaLabel
- findSuitableLocale
- fromCognitoAttributes
- getAADecryptor
- getAAPublicKey
- getMissingDataForInstance
- getNidFromUrn
- getOwnRealVerifications
- getPOVerification
- getSomeoneElsesRealVerifications
- hashPassword
- isConditionMet
- isEncrypted
- isEncryptedFile
- isScoreConfigValid
- isScoreResultValid
- repairDate
- someEncrypted
- sortSchemaProperties
- toCognitoAttributes
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 |
ServerRelationship
Ƭ ServerRelationship: Omit<Relationship, "p_id" | "start" | "end"> & { from_id: NId ; id: PId } & { to_id: NId } | { to_i_id: IId }
This type represents the relationship format returned by the Postgres API
VerDetails
Ƭ VerDetails: Object
Type declaration
| Name | Type | Description |
|---|---|---|
expiryDate? |
Date |
field only present for expired verifications |
sourceNId? |
NId |
- |
verifiers |
VerificationProvider[] |
- |
Functions
calcSafeHarbourScore
▸ 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 |
data.profileObjects |
ProfileObject[] |
data.realVers |
RealVer[] |
data.getSchema |
(schemaName: SchemaName) => Promise<Schema> |
Returns
Promise<SafeHarbourResult>
calculateScore
▸ calculateScore(ruleConfig, ruleInput): Promise<ScoreResult>
the main function to calculate a score and category. Might throw an error.
Parameters
| Name | Type |
|---|---|
ruleConfig |
ScoreConfig |
ruleInput |
RuleData |
Returns
Promise<ScoreResult>
checkJsonSignature
▸ checkJsonSignature(data, signature, keyId): 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 |
keyId |
undefined | string
|
Returns
Promise<boolean>
convertInstanceToRuleInput
▸ convertInstanceToRuleInput(POs, realVers, getSchema): Promise<RuleData>
Parameters
| Name | Type |
|---|---|
POs |
ProfileObject[] |
realVers |
RealVer[] |
getSchema |
(schemaName: SchemaName) => Promise<Schema> |
Returns
Promise<RuleData>
convertServerRelationship
▸ convertServerRelationship(serverRelationship): Relationship
Converts relationship type used by the server into the (Urn format) type used by the client
Parameters
| Name | Type | Description |
|---|---|---|
serverRelationship |
ServerRelationship |
relationship type used in the server |
Returns
Relationship
a Relationship (client-side type) that is equivalent to the inputted serverRelationship value
createAA
▸ createAA(«destructured»): 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 |
|---|---|
«destructured» |
Object |
› apiToken
|
string |
› apiUrl
|
string |
› application
|
Omit<AA, "a_id"> |
› maxcryptor
|
DataEncryptorI |
› userDoc
|
UserDoc |
Returns
Promise<AA>
createHashedNId
▸ createHashedNId(nId, aId): NId
the API returns hashed NIds in a separate field,
which breaks the whole app. So, we move the hashed ID into
the normal n_id field, and use a different format.
This was first introduced in #1048
Parameters
| Name | Type |
|---|---|
nId |
NId |
aId |
AId |
Returns
NId
decryptSharedData
▸ decryptSharedData(«destructured»): Promise<{ applicationDecryptor: ApplicationDataEncryptorI ; instance: Instance }>
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 |
|---|---|
«destructured» |
Object |
› apiToken
|
string |
› apiUrl
|
string |
› instanceData
|
Instance |
› maxcryptor
|
DataEncryptorI |
› onCorruptedData?
|
(fieldName: string, fieldValue: Encrypted, error: Error) => any
|
Returns
Promise<{ applicationDecryptor: ApplicationDataEncryptorI ; instance: Instance }>
a copy of instanceData with all properties decrypted.
evaluateRule
▸ evaluateRule(rule, data): Object
evaluates an individual rule, normally you should use calculateScore
Parameters
| Name | Type |
|---|---|
rule |
ScoreRule |
data |
RuleData |
Returns
Object
| Name | Type |
|---|---|
passed |
boolean |
score |
number |
expandSchema
▸ expandSchema(wrappedSchema, allUnexpandedSchemas, userLocales): Schema
❣️ This is the main function to transform a schema from
the JSON that the API returns, into a Schema object that's useful
to the client.
Parameters
| Name | Type |
|---|---|
wrappedSchema |
WrappedSchema |
allUnexpandedSchemas |
WrappedSchema[] |
userLocales |
readonly string[] |
Returns
Schema
findSchemaLabel
▸ findSchemaLabel(labels): undefined | SchemaName
Finds the label (on a profile object) which is the schema name
Parameters
| Name | Type |
|---|---|
labels |
undefined | string[] |
Returns
undefined | SchemaName
findSuitableLocale
▸ findSuitableLocale(options, langs): undefined | string
Selects the most suitable locale to use from a list of options. Returns undefined if there is no language that the user speaks
Parameters
| Name | Type |
|---|---|
options |
string[] |
langs |
readonly string[] |
Returns
undefined | string
fromCognitoAttributes
▸ 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(«destructured»): Promise<{ decryptor: ApplicationEncryptor ; publicKeyId: KId }>
Fetchs the public and private keys for an Access Application, then initializes
the https://npm.im/@raytio/maxcryptor|Maxcryptor's ApplicationEncryptor.
Parameters
| Name | Type |
|---|---|
«destructured» |
Object |
› aId
|
AId |
› apiToken
|
string |
› apiUrl
|
string |
› maxcryptor
|
DataEncryptorI |
Returns
Promise<{ decryptor: ApplicationEncryptor ; publicKeyId: KId }>
an ApplicationEncryptor and the public key of the Access Application
getAAPublicKey
▸ getAAPublicKey(«destructured»): Promise<PublicKeyNode>
Fetches the Public Key Information for an Access Application
Parameters
| Name | Type |
|---|---|
«destructured» |
Object |
› aId
|
AId |
› apiToken
|
string |
› apiUrl
|
string |
Returns
Promise<PublicKeyNode>
the id and Key information of the Applications Public Key
getMissingDataForInstance
▸ getMissingDataForInstance(«destructured»): Promise<Instance>
the new API doesn't return the whole instance at once, so we have to make several additional API requests.
Parameters
| Name | Type |
|---|---|
«destructured» |
Object |
› apiToken
|
string |
› apiUrl
|
string |
› instanceWithoutData
|
InstanceWithoutData |
Returns
Promise<Instance>
getNidFromUrn
▸ getNidFromUrn<IDType>(urn): IDType
two overloads - if you provide undefined, you might get undefined back
Type parameters
| Name | Type |
|---|---|
IDType |
NId |
Parameters
| Name | Type |
|---|---|
urn |
Urn |
Returns
IDType
▸ getNidFromUrn<IDType>(urn): undefined | IDType
two overloads - if you provide undefined, you might get undefined back
Type parameters
| Name | Type |
|---|---|
IDType |
NId |
Parameters
| Name | Type |
|---|---|
urn |
undefined | Urn
|
Returns
undefined | IDType
getOwnRealVerifications
▸ getOwnRealVerifications(«destructured»): 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 |
|---|---|
«destructured» |
Object |
› profileObjects
|
ProfileObject[] |
› userId
|
UId |
› verifications
|
Verification[] |
Returns
Promise<RealVer[]>
a list of authentic RealVer
getPOVerification
▸ getPOVerification(«destructured»): Object
Determines the verification status of a profile object, and its individual fields.
Parameters
| Name | Type |
|---|---|
«destructured» |
Object |
› PO
|
ProfileObject | ProfileObjectForUpload
|
› realVers
|
RealVer[] |
› schema
|
Schema |
Returns
Object
| Name | Type |
|---|---|
details |
VerDetails |
fieldVerifications |
Record<string, FieldVerification> |
status |
POVerification |
getSomeoneElsesRealVerifications
▸ getSomeoneElsesRealVerifications(«destructured»): 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 |
|---|---|
«destructured» |
Props |
Returns
Promise<RealVer[]>
a list of fileNames/values that are verified.
hashPassword
▸ hashPassword(password): Promise<string>
Deprecated
legacy feature, see #1252
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
▸ isConditionMet(condition, formValues): boolean
Checks all other form values in case any have a trigger value that makes this field required.
Example
[
{ "if": { "age": [17, 18], "city": ["Taupō"] } },
{ "if": { "age": [19, 20] } }
]This means [(age=17 OR age=18) AND (city=Taupō)] OR [(age=19 OR age=20)]
Parameters
| Name | Type |
|---|---|
condition |
Record<string, ConditionValue[]> |
formValues |
Record<string, unknown> |
Returns
boolean
isEncrypted
▸ isEncrypted(value): value is Encrypted
Determines where the input is an encrypted Raytio object
Parameters
| Name | Type | Description |
|---|---|---|
value |
unknown |
anything |
Returns
value is Encrypted
true or false depending on whether the input is an encrypted Raytio object
isEncryptedFile
▸ isEncryptedFile(value): value is Encrypted
Determines where the input is an encrypted Raytio file
Parameters
| Name | Type | Description |
|---|---|---|
value |
unknown |
anything |
Returns
value is Encrypted
true or false depending on whether the input is an encrypted Raytio file
isScoreConfigValid
▸ isScoreConfigValid(x): x is ScoreConfig
determines whether a ScoreConfig object is valid
Parameters
| Name | Type |
|---|---|
x |
unknown |
Returns
x is ScoreConfig
isScoreResultValid
▸ isScoreResultValid(x): x is ScoreResult
determines whether a ScoreResult object is valid
Parameters
| Name | Type |
|---|---|
x |
unknown |
Returns
x is ScoreResult
repairDate
▸ repairDate(date): Date
repairs broken ISO dates into valid JS date objects
Parameters
| Name | Type |
|---|---|
date |
string | Date
|
Returns
Date
someEncrypted
▸ someEncrypted<T>(...args): number
Given a profile object's properties, returns the number of properties that are encryted.
Type parameters
| Name | Type |
|---|---|
T |
extends object
|
Parameters
| Name | Type |
|---|---|
...args |
[obj: T] |
Returns
number
sortSchemaProperties
▸ sortSchemaProperties(properties): Section[]
Schema properties are an object, so they need to be converted into an
array, grouped by the group tag, and then sorted based on the priority
attribute within their group.
Parameters
| Name | Type |
|---|---|
properties |
Record<string, SchemaField> |
Returns
Section[]
toCognitoAttributes
▸ 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