feat: user login process audit

Author: lwin-kyaw

.gitignore

@@ -105,3 +105,5 @@ dist
 
 .env.test
 **/*.DS_Store
+
+.npmrc

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@toruslabs/torus.js",
-  "version": "17.2.2",
+  "version": "17.2.3",
   "description": "Handle communication with torus nodes",
   "main": "dist/lib.cjs/index.js",
   "module": "dist/lib.esm/index.js",

package.json

@@ -1,5 +1,7 @@
-import { BUILD_ENV_TYPE, CITADEL_SERVER_MAP } from "@toruslabs/constants";
-import { get } from "@toruslabs/http-helpers";
+import { BUILD_ENV_TYPE, CITADEL_SERVER_MAP, TORUS_NETWORK_TYPE } from "@toruslabs/constants";
+import { get, put } from "@toruslabs/http-helpers";
+
+import { RetrieveSharesParams } from "../interfaces";
 
 export interface CitadelAllowParams {
   buildEnv: BUILD_ENV_TYPE;
@@ -14,6 +16,24 @@ export interface CitadelAllowParams {
   torusLoginFailed?: boolean;
 }
 
+export interface CitadelAuthFlowAuditParams {
+  oauthInitiated?: boolean;
+  oauthVerified?: boolean;
+  oauthCompleted?: boolean;
+  oauthVerificationFailed?: boolean;
+  oauthFailed?: boolean;
+}
+
+export interface CitadelAuditParams extends CitadelAuthFlowAuditParams {
+  recordId: string;
+  authConnection: string;
+  authConnectionId: string;
+  groupedAuthConnectionId: string;
+  userId: string;
+  web3AuthNetwork: string;
+  web3AuthClientId: string;
+}
+
 export function buildAllowUrl(params: CitadelAllowParams): string {
   const url = new URL(`${CITADEL_SERVER_MAP[params.buildEnv]}/v1/signer/allow`);
   url.searchParams.set("recordid", params.recordId);
@@ -36,10 +56,33 @@ export function buildAllowUrl(params: CitadelAllowParams): string {
   return url.toString();
 }
 
+export function buildAuditPayload(
+  network: TORUS_NETWORK_TYPE,
+  clientId: string,
+  params: RetrieveSharesParams,
+  authFlowAuditParams: CitadelAuthFlowAuditParams
+): CitadelAuditParams {
+  return {
+    ...authFlowAuditParams,
+    recordId: params.recordId,
+    authConnection: params.authConnection || "",
+    authConnectionId: params.verifierParams.sub_verifier_ids?.[0] || "",
+    groupedAuthConnectionId: params.verifier || "",
+    userId: params.verifierParams.verifier_id || "",
+    web3AuthNetwork: network,
+    web3AuthClientId: clientId,
+  };
+}
+
 export async function callAllowApi(params: CitadelAllowParams): Promise<void> {
   await get<void>(buildAllowUrl(params));
 }
 
+export async function callAuditApi(buildEnv: BUILD_ENV_TYPE, params: CitadelAuditParams): Promise<void> {
+  const url = new URL(`${CITADEL_SERVER_MAP[buildEnv]}/v1/user/audit`);
+  await put<void>(url.toString(), params);
+}
+
 export function generateRecordId(): string {
   const cr = typeof globalThis === "object" ? globalThis.crypto : null;
   if (typeof cr?.randomUUID !== "function") throw new Error("crypto.randomUUID must be defined");

src/helpers/citadelUtils.ts

@@ -221,6 +221,7 @@ export interface VerifierParams {
   [key: string]: unknown;
   verifier_id: string;
   extended_verifier_id?: string;
+  sub_verifier_ids?: string[];
 }
 
 export type StringifiedType = Record<string, unknown>;
@@ -283,6 +284,11 @@ export interface ImportKeyParams {
   newPrivateKey: string;
   extraParams?: TorusUtilsExtraParams;
   checkCommitment?: boolean;
+
+  /**
+   * Optional recordId to used for the analytics tracking.
+   */
+  recordId?: string;
 }
 
 export interface RetrieveSharesParams {
@@ -295,4 +301,15 @@ export interface RetrieveSharesParams {
   extraParams?: TorusUtilsExtraParams;
   useDkg?: boolean;
   checkCommitment?: boolean;
+
+  /**
+   * User social login provider name.
+   * This is used for the analytics tracking.
+   */
+  authConnection?: string;
+
+  /**
+   * Optional recordId to used for the analytics tracking.
+   */
+  recordId?: string;
 }

src/interfaces.ts

@@ -4,9 +4,12 @@ import { setAPIKey, setEmbedHost } from "@toruslabs/http-helpers";
 import { config } from "./config";
 import {
   bigintToHex,
+  buildAuditPayload,
   bytesToHex,
   callAllowApi,
+  callAuditApi,
   CitadelAllowParams,
+  CitadelAuthFlowAuditParams,
   Curve,
   encodeEd25519Point,
   generateAddressFromPubKey,
@@ -150,17 +153,24 @@ class Torus {
       extraParams.session_token_exp_second = Torus.sessionTime;
     }
 
+    const recordId = params.recordId || generateRecordId();
+
     const allowParams = {
       buildEnv: this.buildEnv,
       verifier,
       verifierId: verifierParams.verifier_id,
       network: this.network,
       clientId: this.clientId,
       source: this.source,
-      recordId: generateRecordId(),
+      recordId,
     };
 
     let result: TorusKey;
+
+    // report oauth completed
+    // if recordId isn't provided in the params, we will also report oauth initiated
+    this.reportUserAuthFlowAudit({ ...params, recordId }, { oauthCompleted: true, ...(params.recordId ? {} : { oauthInitiated: true }) });
+
     try {
       result = await retrieveOrImportShare({
         recordId: allowParams.recordId,
@@ -185,8 +195,13 @@ class Torus {
         checkCommitment,
         source: this.source,
       });
+
+      // report oauth verified
+      this.reportUserAuthFlowAudit({ ...params, recordId }, { oauthVerified: true, ...(params.recordId ? {} : { oauthInitiated: true }) });
     } catch (error) {
       this.reportSignerAllow({ ...allowParams, torusLoginFailed: true });
+      // report oauth verification failed
+      this.reportUserAuthFlowAudit({ ...params, recordId }, { oauthVerificationFailed: true });
       throw error;
     }
 
@@ -202,6 +217,21 @@ class Torus {
     }
   }
 
+  /**
+   * Report user auth flow audit to the citadel server.
+   * @param recordId - The record id to be used for the analytics tracking.
+   * @param params - The parameters for the retrieve shares operation.
+   * @param authStepStatus - The status of the authentication steps.
+   */
+  async reportUserAuthFlowAudit(params: RetrieveSharesParams, authFlowAuditParams: CitadelAuthFlowAuditParams): Promise<void> {
+    try {
+      const auditParams = buildAuditPayload(this.network, this.clientId, params, authFlowAuditParams);
+      await callAuditApi(this.buildEnv, auditParams);
+    } catch (error) {
+      log.error("Failed to log user auth flow audit", error);
+    }
+  }
+
   async getPublicAddress(
     endpoints: string[],
     torusNodePubs: INodePub[],
@@ -262,8 +292,10 @@ class Torus {
       }
     }
 
+    const recordId = params.recordId || generateRecordId();
+
     return retrieveOrImportShare({
-      recordId: generateRecordId(),
+      recordId,
       legacyMetadataHost: this.legacyMetadataHost,
       serverTimeOffset: this.serverTimeOffset,
       enableOneKey: this.enableOneKey,