Feat: suppot TFGrid-KYC

packages/grid_client/src/client.ts

@@ -5,7 +5,7 @@ import { validateMnemonic } from "bip39";
 import * as PATH from "path";
 import urlJoin from "url-join";
 
-import { Graphql } from "./clients";
+import { Graphql, KYC as kycClient } from "./clients";
 import { TFClient } from "./clients/tf-grid/client";
 import { ClientOptions, GridClientConfig, NetworkEnv } from "./config";
 import { migrateKeysEncryption, send, toHexSeed } from "./helpers";
@@ -24,6 +24,7 @@ class GridClient {
   config: GridClientConfig;
   rmbClient: RMBClient;
   tfclient: TFClient;
+  kycClient: kycClient;
   /**The `MachinesModule` class provides methods to interact with machine operations.*/
   machines: modules.machines;
   k8s: modules.k8s;
@@ -139,7 +140,7 @@ class GridClient {
       this.clientOptions.keypairType,
       this.clientOptions.keepReconnectingToChain,
     );
-
+    this.kycClient = new kycClient(urls.KYC, this.clientOptions.mnemonic, this.clientOptions.keypairType);
     this.rmbClient = new RMBClient(
       urls.substrate,
       urls.relay,
@@ -190,6 +191,7 @@ class GridClient {
       twinId: this.twinId,
       seed: this.clientOptions.seed,
       deploymentTimeoutMinutes: this.clientOptions.deploymentTimeoutMinutes!,
+      kycURL: urls.KYC,
     };
     for (const module of Object.getOwnPropertyNames(modules).filter(item => typeof modules[item] === "function")) {
       if (module.includes("Model")) {
@@ -245,6 +247,8 @@ class GridClient {
       substrate: substrateURL || `wss://tfchain.${base}/ws`,
       graphql: graphqlURL || `https://graphql.${base}/graphql`,
       activation: activationURL || `https://activation.${base}/activation/activate`,
+      //TODO handle kyc url
+      KYC: `kyc1.gent01.dev.grid.tf`,
     };
 
     return urls;

packages/grid_client/src/clients/index.ts

@@ -1,3 +1,4 @@
 export * from "./tf-grid";
 export * from "./graphql";
 export * from "./rmb";
+export * from "./kyc";

packages/grid_client/src/clients/kyc/client.ts

@@ -0,0 +1,190 @@
+import { Keyring } from "@polkadot/keyring";
+import { KeyringPair } from "@polkadot/keyring/types";
+import { waitReady } from "@polkadot/wasm-crypto";
+import { InsufficientBalanceError, KycBaseError, KycErrors, RequestError, ValidationError } from "@threefold/types";
+import { Buffer } from "buffer";
+import urlJoin from "url-join";
+
+import { bytesFromHex, formatErrorMessage, KeypairType, send, stringToHex } from "../..";
+import { KycHeaders, KycStatus, VerificationDataResponse } from "./types";
+const API_PREFIX = "/api/v1/";
+/**
+ * The KYC class provides methods to interact with a TFGid KYC (Know Your Customer) service.
+ * It allows fetching verification data, status, and token by preparing necessary headers
+ * and sending requests to the specified API domain.
+ *
+ * @class KYC
+ * @example
+ * ```typescript
+ * const kyc = new KYC("https://api.example.com", KeypairType.sr25519, "mnemonic");
+ * const data = await kyc.data();
+ * const status = await kyc.status();
+ * const token = await kyc.getToken();
+ * ```
+ * @param {string} apiDomain - The API domain for the KYC service.
+ * @param {KeypairType} [keypairType=KeypairType.sr25519] - The type of keypair to use.
+ * @param {string} mnemonic - The mnemonic for generating the keypair.
+ * @method data - Fetches the verification data from the KYC service.
+ * @method status - Fetches the verification status from the KYC service.
+ * @method getToken - Fetches the token from the KYC service.
+ */
+export class KYC {
+  private keyring: Keyring;
+  private keypair: KeyringPair;
+  public address: string;
+  /**
+   * Creates an instance of KYC.
+   * @param apiDomain - The API domain for the TFGrid KYC service.
+   * @param keypairType - The type of keypair to use (default is sr25519).
+   * @param mnemonic - The mnemonic for generating the keypair.
+   */
+  constructor(
+    public apiDomain: string,
+    private mnemonic: string,
+    public keypairType: KeypairType = KeypairType.sr25519,
+  ) {
+    if (mnemonic === "") {
+      throw new ValidationError("mnemonic is required");
+    }
+    /** The api domain should not contains any prefix or postfix */
+    this.apiDomain = apiDomain.replace("https://", "");
+    this.apiDomain = apiDomain.replace("http://", "");
+    this.apiDomain = apiDomain.replace("/", "");
+  }
+
+  /**
+   * Setup the keypair and the address
+   *
+   * @returns {Promise<void>}
+   * @private
+   */
+  private async setupKeyring() {
+    const keyring = new Keyring({ type: this.keypairType });
+    await waitReady();
+    this.keypair = keyring.addFromUri(this.mnemonic);
+    this.address = this.keypair.address;
+  }
+
+  /**
+   * Prepares the headers required for TFGrid KYC requests.
+   *
+   * This method generates a set of headers that include a timestamp-based challenge,
+   * a signed challenge using the user's key, and other necessary information.
+   *
+   * @returns {Promise<Record<string, string>>} A promise that resolves to an object containing the prepared headers.
+   *
+   */
+  private async prepareHeaders(): Promise<Record<string, string>> {
+    await this.setupKeyring();
+    const timestamp = Date.now();
+    const challenge = stringToHex(`${this.apiDomain}:${timestamp}`);
+    const signedChallenge = this.keypair.sign(bytesFromHex(challenge));
+    const signedMsgHex = Buffer.from(signedChallenge).toString("hex");
+
+    const headers: KycHeaders = {
+      "content-type": "application/json",
+      "X-Client-ID": this.address,
+      "X-Challenge": challenge,
+      "X-Signature": signedMsgHex,
+    };
+    return headers as unknown as Record<string, string>;
+  }
+
+  /**
+   * Throws specific KYC-related errors based on the provided error message.
+   *
+   * @param errorMessage - The error message to evaluate.
+   * @throws {KycErrors.KycInvalidAddressError} If the error message indicates a malformed address.
+   * @throws {KycErrors.KycInvalidChallengeError} If the error message indicates a malformed or bad challenge.
+   * @throws {KycErrors.KycInvalidSignatureError} If the error message indicates a malformed or bad signature.
+   * @returns {undefined} If the error message does not match any known error patterns.
+   */
+  private ThrowHeadersRelatedError(errorMessage: string) {
+    switch (true) {
+      case errorMessage.includes("malformed address"):
+        throw new KycErrors.KycInvalidAddressError(errorMessage);
+      case errorMessage.includes("malformed challenge") || errorMessage.includes("bad challenge"):
+        throw new KycErrors.KycInvalidChallengeError(errorMessage);
+      case errorMessage.includes("malformed signature") || errorMessage.includes("bad signature"):
+        throw new KycErrors.KycInvalidSignatureError(errorMessage);
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Fetches the verification data from the API.
+   *
+   * @returns {Promise<VerificationDataResponse>} A promise that resolves to the verification data response.
+   * @throws {KycErrors.TFGridKycError | KycBaseError} If there is an issue with fetching the data.
+   */
+  async data(): Promise<VerificationDataResponse> {
+    try {
+      const headers = await this.prepareHeaders();
+      return await send("GET", urlJoin("https://", this.apiDomain, API_PREFIX, "data"), "", headers);
+    } catch (error) {
+      const messagePrefix = "Failed to get authentication data from KYC service";
+      const errorMessage = formatErrorMessage(messagePrefix, error);
+      const statusCode = (error as RequestError).statusCode;
+      this.ThrowHeadersRelatedError(errorMessage);
+      if (statusCode === 404) throw new KycErrors.KycUnverifiedError(errorMessage);
+      throw new KycBaseError(errorMessage);
+    }
+  }
+
+  /**
+   * Retrieves the current verification status.
+   *
+   * @returns {Promise<KycStatus>} A promise that resolves to the verification status.
+   * @throws {KycErrors.TFGridKycError | KycBaseError} If there is an issue with fetching the status data.
+   */
+  async status(): Promise<KycStatus> {
+    const headers = await this.prepareHeaders();
+    try {
+      const res = await send("GET", urlJoin("https://", this.apiDomain, API_PREFIX, "status"), "", headers);
+      if (!res.result.status)
+        throw new KycErrors.KycInvalidResponseError(
+          "Failed to get status due to: Response does not contain status field",
+        );
+      return res.result.status;
+    } catch (error) {
+      if (error instanceof RequestError && error.statusCode === 404) return KycStatus.unverified;
+      const messagePrefix = "Failed to get authentication status from KYC service";
+      const errorMessage = formatErrorMessage(messagePrefix, error);
+      this.ThrowHeadersRelatedError(errorMessage);
+      throw new KycBaseError(errorMessage);
+    }
+  }
+  /**
+   * Retrieves a token data from the KYC service API.
+   *
+   * @returns {Promise<string>} A promise that resolves to a string representing the idenify auth token .
+   * @throws {KycErrors.TFGridKycError | KycBaseError} If there is an issue with fetching the token data.
+   */
+  async getToken(): Promise<string> {
+    try {
+      const headers = await this.prepareHeaders();
+      const res = await send("POST", urlJoin("https://", this.apiDomain, API_PREFIX, "token"), "", headers);
+      if (!res.result.authToken)
+        throw new KycErrors.KycInvalidResponseError(
+          "Failed to get token due to: Response does not contain authToken field",
+        );
+      return res.result.authToken;
+    } catch (error) {
+      const messagePrefix = "Failed to get auth token from KYC service";
+      const errorMessage = formatErrorMessage(messagePrefix, error);
+      const statusCode = (error as RequestError).statusCode;
+      this.ThrowHeadersRelatedError(errorMessage);
+      switch (true) {
+        case statusCode === 429:
+          throw new KycErrors.KycRateLimitError(errorMessage);
+        case errorMessage.includes("already verified"):
+          throw new KycErrors.KycAlreadyVerifiedError(errorMessage);
+        case errorMessage.includes("balance"):
+          throw new InsufficientBalanceError(errorMessage);
+        default:
+          throw new KycBaseError(errorMessage);
+      }
+    }
+  }
+}

packages/grid_client/src/clients/kyc/index.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

packages/grid_client/src/clients/kyc/types.ts

@@ -0,0 +1,90 @@
+/**
+ * KYC service token response type
+ */
+export interface TokenResponse {
+  authToken: string;
+  clientId: string;
+  digitString: string;
+  expiryTime: number;
+  message: string;
+  scanRef: string;
+  sessionLength: number;
+  tokenType: string;
+}
+/**
+ * @interface VerificationStatusResponse
+ * KYC service token response type
+ */
+export interface VerificationStatusResponse {
+  autoDocument: string;
+  autoFace: string;
+  clientId: string;
+  fraudTags: string[];
+  manualDocument: string;
+  manualFace: string;
+  mismatchTags: string[];
+  scanRef: string;
+  status: string;
+}
+
+export interface VerificationDataResponse {
+  additionalData: object;
+  address: string;
+  addressVerification: object;
+  ageEstimate: string;
+  authority: string;
+  birthPlace: string;
+  clientId: string;
+  clientIpProxyRiskLevel: string;
+  docBirthName: string;
+  docDateOfIssue: string;
+  docDob: string;
+  docExpiry: string;
+  docFirstName: string;
+  docIssuingCountry: string;
+  docLastName: string;
+  docNationality: string;
+  docNumber: string;
+  docPersonalCode: string;
+  docSex: string;
+  docTemporaryAddress: string;
+  docType: string;
+  driverLicenseCategory: string;
+  duplicateDocFaces: string[];
+  duplicateFaces: string[];
+  fullName: string;
+  manuallyDataChanged: boolean;
+  mothersMaidenName: string;
+  orgAddress: string;
+  orgAuthority: string;
+  orgBirthName: string;
+  orgBirthPlace: string;
+  orgFirstName: string;
+  orgLastName: string;
+  orgMothersMaidenName: string;
+  orgNationality: string;
+  orgTemporaryAddress: string;
+  scanRef: string;
+  selectedCountry: string;
+}
+
+/**
+ * Interface representing the headers required for KYC (Know Your Customer) requests.
+ *
+ * @property {string} content-type - The MIME type of the request body.
+ * @property {string} X-Client-ID - TF chian address
+ * @property {string} X-Challenge - hex-encoded message `{api-domain}:{timestamp}`.
+ * @property {string} X-Signature - hex-encoded sr25519|ed25519 signature.
+ */
+export interface KycHeaders {
+  "content-type": string;
+  "X-Client-ID": string;
+  "X-Challenge": string;
+  "X-Signature": string;
+}
+export enum KycStatus {
+  unverified = "UNVERIFIED",
+  verified = "VERIFIED",
+  rejected = "REJECTED",
+  pending = "PENDING",
+}

packages/grid_client/src/config.ts

@@ -31,6 +31,7 @@ class GridClientConfig {
   twinId: number;
   seed?: string;
   deploymentTimeoutMinutes: number;
+  kycURL: string;
 }
 class ClientOptions {
   constructor(
@@ -49,6 +50,7 @@ class ClientOptions {
     public activationURL?: string,
     public deploymentTimeoutMinutes?: number,
     public keepReconnectingToChain?: boolean,
+    public KycURL?: string,
   ) {}
 }
 

packages/grid_client/src/helpers/utils.ts

@@ -81,6 +81,22 @@ function convertObjectToQueryString(obj: Record<string, any>): string {
 
   return queryString;
 }
+/**
+ * Converts a string message to its hexadecimal representation.
+ * @param message - The message to convert.
+ * @returns The hexadecimal representation of the message.
+ */
+function stringToHex(message: string): string {
+  return Buffer.from(message).toString("hex");
+}
+/**
+ * Converts a hexadecimal string to a byte array.
+ * @param hex - The hexadecimal string to convert.
+ * @returns {Uint8Array} The byte array representation of the hexadecimal string.
+ */
+function bytesFromHex(hex: string): Uint8Array {
+  return new Uint8Array(Buffer.from(hex, "hex"));
+}
 
 export {
   generateString,
@@ -95,4 +111,6 @@ export {
   generateRandomHexSeed,
   zeroPadding,
   convertObjectToQueryString,
+  stringToHex,
+  bytesFromHex,
 };