feat: track auth flow

.gitignore

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

src/helpers/citadelUtils.ts

@@ -1,5 +1,21 @@
-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";
+import { isNullOrUndefined } from "./common";
+
+export enum CitadelAllowParamsSetOrUnsetFlag {
+  SET = 1,
+  UNSET = 0,
+}
+
+export interface CitadelAuthFlowAuditParams {
+  oauthInitiated?: boolean;
+  oauthVerified?: boolean;
+  oauthCompleted?: boolean;
+  oauthVerificationFailed?: boolean;
+  oauthFailed?: boolean;
+}
 
 export interface CitadelAllowParams {
   buildEnv: BUILD_ENV_TYPE;
@@ -9,9 +25,22 @@ export interface CitadelAllowParams {
   clientId: string;
   recordId: string;
   source?: string;
-  torusLoginInitiated?: boolean;
-  torusLoginSuccess?: boolean;
-  torusLoginFailed?: boolean;
+  // flags for auditing the auth flow
+  oauthInitiated?: CitadelAllowParamsSetOrUnsetFlag;
+  oauthVerified?: CitadelAllowParamsSetOrUnsetFlag;
+  oauthCompleted?: CitadelAllowParamsSetOrUnsetFlag;
+  oauthVerificationFailed?: CitadelAllowParamsSetOrUnsetFlag;
+  oauthFailed?: CitadelAllowParamsSetOrUnsetFlag;
+}
+
+export interface CitadelAuditParams extends CitadelAuthFlowAuditParams {
+  recordId: string;
+  authConnection: string;
+  authConnectionId: string;
+  groupedAuthConnectionId: string;
+  oAuthUserId: string;
+  web3AuthNetwork: string;
+  web3AuthClientId: string;
 }
 
 export function buildAllowUrl(params: CitadelAllowParams): string {
@@ -24,22 +53,55 @@ export function buildAllowUrl(params: CitadelAllowParams): string {
   if (params.source) {
     url.searchParams.set("source", params.source);
   }
-  if (typeof params.torusLoginInitiated !== "undefined") {
-    url.searchParams.set("toruslogininitiated", params.torusLoginInitiated.toString());
+  if (!isNullOrUndefined(params.oauthInitiated)) {
+    url.searchParams.set("oauthInitiated", params.oauthInitiated.toString());
   }
-  if (typeof params.torusLoginSuccess !== "undefined") {
-    url.searchParams.set("torusloginsuccess", params.torusLoginSuccess.toString());
+  if (!isNullOrUndefined(params.oauthVerified)) {
+    url.searchParams.set("oauthVerified", params.oauthVerified.toString());
   }
-  if (typeof params.torusLoginFailed !== "undefined") {
-    url.searchParams.set("torusloginfailed", params.torusLoginFailed.toString());
+  if (!isNullOrUndefined(params.oauthCompleted)) {
+    url.searchParams.set("oauthCompleted", params.oauthCompleted.toString());
+  }
+  if (!isNullOrUndefined(params.oauthVerificationFailed)) {
+    url.searchParams.set("oauthVerificationFailed", params.oauthVerificationFailed.toString());
+  }
+  if (!isNullOrUndefined(params.oauthFailed)) {
+    url.searchParams.set("oauthFailed", params.oauthFailed.toString());
   }
   return url.toString();
 }
 
+export function buildAuditPayload(
+  network: TORUS_NETWORK_TYPE,
+  clientId: string,
+  params: RetrieveSharesParams,
+  authFlowAuditParams: CitadelAuthFlowAuditParams
+): CitadelAuditParams {
+  if (!params.recordId) {
+    params.recordId = generateRecordId();
+  }
+
+  return {
+    ...authFlowAuditParams,
+    recordId: params.recordId,
+    authConnection: params.authConnection || "",
+    authConnectionId: params.verifierParams.sub_verifier_ids?.[0] || "",
+    groupedAuthConnectionId: params.verifier || "",
+    oAuthUserId: 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/auth/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/common.ts

@@ -161,3 +161,7 @@ export function retryCommitment(executionPromise: () => Promise<JRPCResponse<Com
 
   return retryWithBackoff(0);
 }
+
+export function isNullOrUndefined(value: unknown): value is null | undefined {
+  return value === null || value === undefined;
+}

src/helpers/nodeUtils.ts

@@ -27,7 +27,7 @@ import {
 import log from "../loglevel";
 import { Some } from "../some";
 import { TorusUtilsExtraParams } from "../TorusUtilsExtraParams";
-import { callAllowApi } from "./citadelUtils";
+import { callAllowApi, CitadelAllowParamsSetOrUnsetFlag } from "./citadelUtils";
 import {
   base64ToBytes,
   bigintToHex,
@@ -390,6 +390,7 @@ export async function retrieveOrImportShare(params: {
     source,
     recordId,
   } = params;
+  // call feature-gating check before share retrieval
   await callAllowApi({
     buildEnv,
     verifier,
@@ -398,7 +399,8 @@ export async function retrieveOrImportShare(params: {
     clientId,
     source,
     recordId,
-    torusLoginInitiated: true,
+    oauthInitiated: CitadelAllowParamsSetOrUnsetFlag.SET,
+    oauthCompleted: CitadelAllowParamsSetOrUnsetFlag.SET,
   });
 
   // generate temporary private and public key that is used to secure receive shares

src/interfaces.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;
 }