Add email magic link verification (#80)

Author: hwhmeikle

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@authsignal/browser",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",

src/api/email-magic-link-api-client.ts

@@ -0,0 +1,71 @@
+import {ChallengeResponse, EnrollResponse} from "../types";
+import {buildHeaders, handleTokenExpired} from "./helpers";
+import {CheckVerificationStatusResponse} from "./types/email-magic-link";
+import {ApiClientOptions, ErrorResponse} from "./types/shared";
+
+export class EmailMagicLinkApiClient {
+  tenantId: string;
+  baseUrl: string;
+  onTokenExpired?: () => void;
+
+  constructor({baseUrl, tenantId, onTokenExpired}: ApiClientOptions) {
+    this.tenantId = tenantId;
+    this.baseUrl = baseUrl;
+    this.onTokenExpired = onTokenExpired;
+  }
+
+  async enroll({token, email}: {token: string; email: string}): Promise<EnrollResponse | ErrorResponse> {
+    const body = {email};
+
+    const response = await fetch(`${this.baseUrl}/client/user-authenticators/email-magic-link`, {
+      method: "POST",
+      headers: buildHeaders({token, tenantId: this.tenantId}),
+      body: JSON.stringify(body),
+    });
+
+    const responseJson = await response.json();
+
+    handleTokenExpired({response: responseJson, onTokenExpired: this.onTokenExpired});
+
+    return responseJson;
+  }
+
+  async challenge({token}: {token: string}): Promise<ChallengeResponse | ErrorResponse> {
+    const response = await fetch(`${this.baseUrl}/client/challenge/email-magic-link`, {
+      method: "POST",
+      headers: buildHeaders({token, tenantId: this.tenantId}),
+    });
+
+    const responseJson = await response.json();
+
+    handleTokenExpired({response: responseJson, onTokenExpired: this.onTokenExpired});
+
+    return responseJson;
+  }
+
+  async checkVerificationStatus({token}: {token: string}): Promise<CheckVerificationStatusResponse | ErrorResponse> {
+    const pollVerificationStatus = async (): Promise<CheckVerificationStatusResponse | ErrorResponse> => {
+      const response = await fetch(`${this.baseUrl}/client/verify/email-magic-link/finalize`, {
+        method: "POST",
+        headers: buildHeaders({token, tenantId: this.tenantId}),
+        body: JSON.stringify({}),
+      });
+
+      const responseJson = await response.json();
+
+      handleTokenExpired({response: responseJson, onTokenExpired: this.onTokenExpired});
+
+      if (responseJson.isVerified) {
+        return responseJson;
+      } else {
+        return new Promise((resolve) => {
+          setTimeout(async () => {
+            resolve(await pollVerificationStatus());
+          }, 1000);
+        });
+      }
+    };
+
+    return await pollVerificationStatus();
+  }
+}

src/api/types/email-magic-link.ts

@@ -0,0 +1,4 @@
+export type CheckVerificationStatusResponse = {
+  isVerified: boolean;
+  accessToken?: string;
+};

src/authsignal.ts

@@ -16,6 +16,7 @@ import {Totp} from "./totp";
 import {TokenCache} from "./token-cache";
 import {Email} from "./email";
 import {Sms} from "./sms";
+import {EmailMagicLink} from "./email-magic-link";
 
 const DEFAULT_COOKIE_NAME = "__as_aid";
 const DEFAULT_PROFILING_COOKIE_NAME = "__as_pid";
@@ -33,6 +34,7 @@ export class Authsignal {
   passkey: Passkey;
   totp: Totp;
   email: Email;
+  emailML: EmailMagicLink;
   sms: Sms;
 
   constructor({
@@ -68,6 +70,7 @@ export class Authsignal {
     this.passkey = new Passkey({tenantId, baseUrl, anonymousId: this.anonymousId, onTokenExpired});
     this.totp = new Totp({tenantId, baseUrl, onTokenExpired});
     this.email = new Email({tenantId, baseUrl, onTokenExpired});
+    this.emailML = new EmailMagicLink({tenantId, baseUrl, onTokenExpired});
     this.sms = new Sms({tenantId, baseUrl, onTokenExpired});
   }
 

src/email-magic-link.ts

@@ -0,0 +1,58 @@
+import {EmailMagicLinkApiClient} from "./api/email-magic-link-api-client";
+import {CheckVerificationStatusResponse} from "./api/types/email-magic-link";
+import {handleApiResponse} from "./helpers";
+import {TokenCache} from "./token-cache";
+import {AuthsignalResponse, ChallengeResponse, EnrollResponse} from "./types";
+
+type EmailMagicLinkOptions = {
+  baseUrl: string;
+  tenantId: string;
+  onTokenExpired?: () => void;
+};
+
+type EnrollParams = {
+  email: string;
+};
+
+export class EmailMagicLink {
+  private api: EmailMagicLinkApiClient;
+  private cache = TokenCache.shared;
+
+  constructor({baseUrl, tenantId, onTokenExpired}: EmailMagicLinkOptions) {
+    this.api = new EmailMagicLinkApiClient({baseUrl, tenantId, onTokenExpired});
+  }
+
+  async enroll({email}: EnrollParams): Promise<AuthsignalResponse<EnrollResponse>> {
+    if (!this.cache.token) {
+      return this.cache.handleTokenNotSetError();
+    }
+
+    const response = await this.api.enroll({token: this.cache.token, email});
+
+    return handleApiResponse(response);
+  }
+
+  async challenge(): Promise<AuthsignalResponse<ChallengeResponse>> {
+    if (!this.cache.token) {
+      return this.cache.handleTokenNotSetError();
+    }
+
+    const response = await this.api.challenge({token: this.cache.token});
+
+    return handleApiResponse(response);
+  }
+
+  async checkVerificationStatus(): Promise<AuthsignalResponse<CheckVerificationStatusResponse>> {
+    if (!this.cache.token) {
+      return this.cache.handleTokenNotSetError();
+    }
+
+    const response = await this.api.checkVerificationStatus({token: this.cache.token});
+
+    if ("accessToken" in response && response.accessToken) {
+      this.cache.token = response.accessToken;
+    }
+
+    return handleApiResponse(response);
+  }
+}