Feat: suppot TFGrid-KYC

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

@@ -0,0 +1,131 @@
+import { Keyring } from "@polkadot/keyring";
+import { KeyringPair } from "@polkadot/keyring/types";
+import { waitReady } from "@polkadot/wasm-crypto";
+
+import { KeypairType, send } from "../..";
+import { KycHeaders, TokenResponse, VerificationDataResponse, VerificationStatusResponse } from "./types";
+
+/**
+ * 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", "TFChain-address", KeypairType.sr25519, "mnemonic");
+ * const data = await kyc.data();
+ * const status = await kyc.status();
+ * const token = await kyc.token();
+ * ```
+ * @param {string} apiDomain - The API domain for the KYC service.
+ * @param {string} address - The TFChain address.
+ * @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 token - Fetches the token from the KYC service.
+ */
+export default class KYC {
+  private keyr: Keyring;
+  /**
+   * Creates an instance of KYC.
+   * @param apiDomain - The API domain for the TFGrid KYC service.
+   * @param address - The TFChain user address.
+   * @param keypairType - The type of keypair to use (default is sr25519).
+   * @param mnemonic - The mnemonic for generating the keypair.
+   */
+  constructor(
+    public apiDomain: string,
+    public address: string,
+    public keypairType: KeypairType = KeypairType.sr25519,
+    private mnemonic: string,
+  ) {
+    this.keyr = new Keyring({ type: keypairType });
+  }
+
+  /**
+   * Retrieves a key pair from the mnemonic.
+   *
+   * @returns {Promise<KeyringPair>} A promise that resolves to a KeyringPair object.
+   * @private
+   */
+  private async getKey(): Promise<KeyringPair> {
+    await waitReady();
+    return this.keyr.addFromUri(this.mnemonic);
+  }
+  /**
+   * Converts a string message to its hexadecimal representation.
+   * @param message - The message to convert.
+   * @returns The hexadecimal representation of the message.
+   */
+  private 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.
+   */
+  private bytesFromHex(hex: string): Uint8Array {
+    return new Uint8Array(Buffer.from(hex, "hex"));
+  }
+
+  /**
+   * 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>> {
+    const timestamp = Date.now();
+    const challenge = this.stringToHex(`${this.apiDomain}:${timestamp}`);
+    const key = await this.getKey();
+    const signedChallenge = key.sign(this.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>;
+  }
+
+  /**
+   * Fetches the verification data from the API.
+   *
+   * @returns {Promise<VerificationDataResponse>} A promise that resolves to the verification data response.
+   * @throws {RequestError} If there is an issue with fetching the data.
+   */
+  async data(): Promise<VerificationDataResponse> {
+    const headers = await this.prepareHeaders();
+    return (await send("GET", `${this.apiDomain}/data`, "", headers)) as VerificationDataResponse;
+  }
+
+  /**
+   * Retrieves the current verification status.
+   *
+   * @returns {Promise<VerificationStatusResponse>} A promise that resolves to the verification status response.
+   * @throws {RequestError} If there is an issue with fetching the status data.
+   */
+  async status(): Promise<VerificationStatusResponse> {
+    const headers = await this.prepareHeaders();
+    return (await send("GET", `${this.apiDomain}/status`, "", headers)) as VerificationStatusResponse;
+  }
+
+  /**
+   * Retrieves a token data from the KYC service API.
+   *
+   * @returns {Promise<TokenResponse>} A promise that resolves to a TokenResponse object.
+   * @throws {RequestError} If there is an issue with fetching the token data.
+   */
+  async token(): Promise<TokenResponse> {
+    const headers = await this.prepareHeaders();
+    return (await send("POST", `${this.apiDomain}/token`, "", headers)) as TokenResponse;
+  }
+}

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

@@ -0,0 +1,84 @@
+/**
+ * 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;
+}