@raytio/core 8.1.0 → 9.0.0

package/README.md

@@ -10,6 +10,465 @@ Nodejs does not support [fetch](https://developer.mozilla.org/en-US/docs/Web/API
 
 If you use the high-level [`@raytio/decrypt-helper`](https://npm.im/@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](https://gitlab.com/raytio/tools/decrypt-helper/-/blob/master/src/configureEnv.ts)
+If you wish to use `@raytio/core` directly, an example of configuring polyfills for nodejs is availble [here](https://gitlab.com/raytio/tools/decrypt-helper/-/blob/main/src/configureEnv.ts)
 
 # API
+
+## Table of contents
+
+### Type aliases
+
+- [SafeHarbourObj](#safeharbourobj)
+- [SafeHarbourResult](#safeharbourresult)
+
+### Functions
+
+- [calcSafeHarbourScore](#calcsafeharbourscore)
+- [calculateScore](#calculatescore)
+- [cleanInstance](#cleaninstance)
+- [convertInstanceToRuleInput](#convertinstancetoruleinput)
+- [createAA](#createaa)
+- [decryptSharedData](#decryptshareddata)
+- [findSchemaLabel](#findschemalabel)
+- [fromCognitoAttributes](#fromcognitoattributes)
+- [getAADecryptor](#getaadecryptor)
+- [getOwnRealVerifications](#getownrealverifications)
+- [getPOVerification](#getpoverification)
+- [getSomeoneElsesRealVerifications](#getsomeoneelsesrealverifications)
+- [hashPassword](#hashpassword)
+- [isConditionMet](#isconditionmet)
+- [isEncrypted](#isencrypted)
+- [isEncryptedFile](#isencryptedfile)
+- [someEncrypted](#someencrypted)
+- [toCognitoAttributes](#tocognitoattributes)
+
+## Type aliases
+
+### SafeHarbourObj
+
+Ƭ **SafeHarbourObj**: `Partial`<`Record`<`SafeHarbourCode`, `string`[]\>\>
+
+an object listing the `xId`s for each SafeHarbourCode
+
+___
+
+### SafeHarbourResult
+
+Ƭ **SafeHarbourResult**: `Object`
+
+the response from [calcSafeHarbourScore](#calcsafeharbourscore)
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `flags` | [`SafeHarbourObj`](#safeharbourobj) |
+| `isSafe` | `boolean` |
+
+## Functions
+
+### calcSafeHarbourScore
+
+▸ `Const` **calcSafeHarbourScore**(`data`): `Promise`<[`SafeHarbourResult`](#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](https://dev-docs.rayt.io/docs/features/pep-checks).
+
+#### 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`](#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`
+
+___
+
+### 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_id`s 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](https://npm.im/@raytio/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`

package/dist/accessApplication/createAA.js

@@ -46,7 +46,6 @@ async function createApplicationEncryptor(userDoc, maxcryptor) {
  */
 async function createAA({ apiUrl, apiToken, userDoc, maxcryptor, application, }) {
     if (!application.org_id) {
-        // eslint-disable-next-line fp/no-throw
         throw new Error("Cannot create an AA without an org_id");
     }
     const newApp = await createApplication({

package/dist/crypto/decryptKeys.js

@@ -13,7 +13,6 @@ const decryptKeys = async ({ applicationDecryptor, keys, data, onCorruptedData,
             const error = new Error(`Can't decrypt shared data because there are no keys for ${key}`);
             if (onCorruptedData)
                 return [key, onCorruptedData(key, value, error)];
-            // eslint-disable-next-line fp/no-throw
             throw error;
         }
         try {
@@ -26,7 +25,6 @@ const decryptKeys = async ({ applicationDecryptor, keys, data, onCorruptedData,
             const error = _ex instanceof Error ? _ex : new Error(`${_ex}`);
             if (onCorruptedData)
                 return [key, onCorruptedData(key, value, error)];
-            // eslint-disable-next-line fp/no-throw
             throw error;
         }
     }));

package/dist/crypto/decryptSharedData.js

@@ -20,15 +20,18 @@ const decryptSharedData = async ({ instanceData, maxcryptor, apiUrl, apiToken, o
         apiUrl,
         apiToken,
     });
-    const instance = Object.assign(Object.assign({}, instanceData), { profile_objects: await Promise.all(instanceData.profile_objects.map(async (profileObject) => {
-            const keys = instanceData.keys[profileObject.n_id];
+    const instance = Object.assign(Object.assign({}, instanceData), { profile_objects: await Promise.all(instanceData.profile_objects.map(async (PO) => {
+            const realNId = PO.n_id.startsWith("HASHED::")
+                ? PO.n_id.split("::")[1]
+                : PO.n_id;
+            const keys = instanceData.keys[realNId];
             const decryptedProperties = await (0, decryptKeys_1.decryptKeys)({
                 applicationDecryptor,
                 keys,
-                data: profileObject.properties,
+                data: PO.properties,
                 onCorruptedData,
             });
-            return Object.assign(Object.assign({}, profileObject), { properties: decryptedProperties });
+            return Object.assign(Object.assign({}, PO), { properties: decryptedProperties });
         })) });
     return { instance, applicationDecryptor };
 };

package/dist/crypto/helpers.d.ts

@@ -15,4 +15,4 @@ export declare const isEncryptedFile: (value: unknown) => value is Encrypted<str
  * Given a profile object's properties, returns the number
  * of properties that are encryted.
  */
-export declare const someEncrypted: <T extends object, K extends keyof T>(x: T) => number;
+export declare const someEncrypted: <T extends object, K extends keyof T>(obj: T) => number;

package/dist/general/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./conditional";
 export * from "./password";
+export * from "./types";

package/dist/general/index.js

@@ -12,3 +12,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./conditional"), exports);
 __exportStar(require("./password"), exports);
+__exportStar(require("./types"), exports);

package/dist/general/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * to prevent a key from the JS object prototype (e.g. `__proto__`) from
+ * returning an unexpected value (see #1162)
+ * @ignore
+ */
+export declare function assertSafeProperty(key: string): asserts key is string;

package/dist/general/types.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafeProperty = void 0;
+/**
+ * to prevent a key from the JS object prototype (e.g. `__proto__`) from
+ * returning an unexpected value (see #1162)
+ * @ignore
+ */
+function assertSafeProperty(key) {
+    if (key in {})
+        throw new Error("Unacceptable object property");
+}
+exports.assertSafeProperty = assertSafeProperty;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./accessApplication";
 export * from "./crypto";
 export * from "./general";
+export * from "./rules";
 export * from "./schema";
 export * from "./verifications";

package/dist/index.js

@@ -13,5 +13,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./accessApplication"), exports);
 __exportStar(require("./crypto"), exports);
 __exportStar(require("./general"), exports);
+__exportStar(require("./rules"), exports);
 __exportStar(require("./schema"), exports);
 __exportStar(require("./verifications"), exports);

package/dist/rules/calculateScore.d.ts

@@ -0,0 +1,11 @@
+import { RuleData, ScoreConfig } from "./types";
+/** @ignore */
+export declare type ScoreResult = {
+    score: number;
+    category: string;
+};
+/**
+ * the main function to calculate a score and category.
+ * Might throw an error.
+ */
+export declare function calculateScore(ruleConfig: ScoreConfig, ruleInput: RuleData): ScoreResult;

package/dist/rules/calculateScore.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateScore = void 0;
+const evaluateScoreCondition_1 = require("./evaluateScoreCondition");
+const helpers_1 = require("./helpers");
+function evaluateASTNode(node, data) {
+    if (node.type === "LanguageOperator") {
+        if (!node.children.length) {
+            // we allow a single child because why not.
+            throw new Error("LanguageOperator has no children");
+        }
+        if (node.operator === "AND") {
+            return node.children.every(n => evaluateASTNode(n, data));
+        }
+        if (node.operator === "OR") {
+            return node.children.some(n => evaluateASTNode(n, data));
+        }
+        throw new Error(`LanguageOperator node has invalid operator '${node.operator}'`);
+    }
+    if (node.type === "ScoreCondition") {
+        return (0, evaluateScoreCondition_1.evaluateScoreCondition)(node, data);
+    }
+    throw new Error("ASTNode has invalid type");
+}
+function evaluateRule(rule, data) {
+    if (rule.tree.length !== 1) {
+        throw new Error("A rule may only have 1 root node");
+    }
+    const rulePassed = rule.tree.every(n => evaluateASTNode(n, data));
+    return rulePassed ? rule.trueWeight : rule.falseWeight;
+}
+/**
+ * the main function to calculate a score and category.
+ * Might throw an error.
+ */
+function calculateScore(ruleConfig, ruleInput) {
+    const result = ruleConfig.rules.map(rule => evaluateRule(rule, ruleInput));
+    const [addOrMultiply, initialValue] = (0, helpers_1.getCombinator)(ruleConfig.combinator);
+    const finalScore = result.reduce(addOrMultiply, initialValue);
+    const matchingCategories = (0, helpers_1.addInfiniteThresholdBoundaries)(ruleConfig.scoreThresholds).filter(threshold => finalScore >= threshold.from && finalScore <= threshold.to);
+    if (matchingCategories.length === 0) {
+        throw new Error(`No categories match the final score (${finalScore})`);
+    }
+    if (matchingCategories.length !== 1) {
+        throw new Error(`Multiple categories match the final score (${finalScore})`);
+    }
+    return {
+        score: finalScore,
+        category: matchingCategories[0].name,
+    };
+}
+exports.calculateScore = calculateScore;

package/dist/rules/convertInstanceToRuleInput.d.ts

@@ -0,0 +1,3 @@
+import { Instance, RealVer, Schema } from "@raytio/types";
+import { RuleData } from "./types";
+export declare const convertInstanceToRuleInput: (instance: Instance, realVers: RealVer[], getSchema: (schemaName: string) => Promise<Schema>) => Promise<RuleData>;