feat(experience): add one-time token landing page to handle magic link auth

Author: charIeszhao

packages/experience/src/App.tsx

@@ -24,6 +24,7 @@ import MfaVerification from './pages/MfaVerification';
 import BackupCodeVerification from './pages/MfaVerification/BackupCodeVerification';
 import TotpVerification from './pages/MfaVerification/TotpVerification';
 import WebAuthnVerification from './pages/MfaVerification/WebAuthnVerification';
+import OneTimeToken from './pages/OneTimeToken';
 import Register from './pages/Register';
 import RegisterPassword from './pages/RegisterPassword';
 import ResetPassword from './pages/ResetPassword';
@@ -37,6 +38,7 @@ import SocialLanding from './pages/SocialLanding';
 import SocialLinkAccount from './pages/SocialLinkAccount';
 import SocialSignInWebCallback from './pages/SocialSignInWebCallback';
 import Springboard from './pages/Springboard';
+import SwitchAccount from './pages/SwitchAccount';
 import VerificationCode from './pages/VerificationCode';
 import { UserMfaFlow } from './types';
 import { handleSearchParametersData } from './utils/search-parameters';
@@ -61,7 +63,7 @@ const App = () => {
                     element={<SocialSignInWebCallback />}
                   />
                   <Route path="direct/:method/:target?" element={<DirectSignIn />} />
-
+                  <Route path="token/:token" element={<OneTimeToken />} />
                   <Route element={<AppLayout />}>
                     <Route
                       path="unknown-session"
@@ -153,8 +155,9 @@ const App = () => {
                       path={experience.routes.resetPassword}
                       element={<ResetPasswordLanding />}
                     />
-
-                    <Route path="*" element={<ErrorPage />} />
+                    <Route path={experience.routes.switchAccount} element={<SwitchAccount />} />
+                    <Route path={experience.routes.error} element={<ErrorPage />} />
+                    <Route path="*" element={<ErrorPage title="description.not_found" />} />
                   </Route>
                 </Route>
               </Routes>

packages/experience/src/apis/experience/index.ts

@@ -28,6 +28,7 @@ export {
 
 export * from './mfa';
 export * from './social';
+export * from './one-time-token';
 
 export const registerWithVerifiedIdentifier = async (verificationId: string) => {
   await updateInteractionEvent(InteractionEvent.Register);

packages/experience/src/apis/experience/one-time-token.ts

@@ -0,0 +1,16 @@
+import { InteractionEvent, type OneTimeTokenVerificationVerifyPayload } from '@logto/schemas';
+
+import api from '../api';
+
+import { experienceApiRoutes, type VerificationResponse } from './const';
+import { initInteraction } from './interaction';
+
+export const verifyOneTimeToken = async (payload: OneTimeTokenVerificationVerifyPayload) => {
+  await initInteraction(InteractionEvent.Register);
+
+  return api
+    .post(`${experienceApiRoutes.verification}/one-time-token/verify`, {
+      json: payload,
+    })
+    .json<VerificationResponse>();
+};

packages/experience/src/hooks/use-fallback-route.ts

@@ -0,0 +1,13 @@
+import { experience } from '@logto/schemas';
+import { useMemo } from 'react';
+
+const useFallbackRoute = () =>
+  useMemo(() => {
+    const fallbackKey = new URLSearchParams(window.location.search).get('fallback');
+    return (
+      Object.entries(experience.routes).find(([key]) => key === fallbackKey)?.[1] ??
+      experience.routes.signIn
+    );
+  }, []);
+
+export default useFallbackRoute;

packages/experience/src/pages/DirectSignIn/index.tsx

@@ -1,9 +1,9 @@
-import { experience } from '@logto/schemas';
-import { useEffect, useMemo } from 'react';
+import { useEffect } from 'react';
 import { useParams } from 'react-router-dom';
 
 import LoadingLayer from '@/components/LoadingLayer';
 import useSocial from '@/containers/SocialSignInList/use-social';
+import useFallbackRoute from '@/hooks/use-fallback-route';
 import { useSieMethods } from '@/hooks/use-sie';
 import useSingleSignOn from '@/hooks/use-single-sign-on';
 
@@ -12,13 +12,7 @@ const DirectSignIn = () => {
   const { socialConnectors, ssoConnectors } = useSieMethods();
   const { invokeSocialSignIn } = useSocial();
   const invokeSso = useSingleSignOn();
-  const fallback = useMemo(() => {
-    const fallbackKey = new URLSearchParams(window.location.search).get('fallback');
-    return (
-      Object.entries(experience.routes).find(([key]) => key === fallbackKey)?.[1] ??
-      experience.routes.signIn
-    );
-  }, []);
+  const fallback = useFallbackRoute();
 
   useEffect(() => {
     if (method === 'social') {

packages/experience/src/pages/OneTimeToken/index.tsx

@@ -0,0 +1,139 @@
+import { AgreeToTermsPolicy, SignInIdentifier } from '@logto/schemas';
+import { useCallback, useEffect, useState } from 'react';
+import { useParams } from 'react-router-dom';
+
+import {
+  identifyAndSubmitInteraction,
+  signInWithVerifiedIdentifier,
+  verifyOneTimeToken,
+} from '@/apis/experience';
+import LoadingLayer from '@/components/LoadingLayer';
+import useApi from '@/hooks/use-api';
+import useErrorHandler from '@/hooks/use-error-handler';
+import useFallbackRoute from '@/hooks/use-fallback-route';
+import useGlobalRedirectTo from '@/hooks/use-global-redirect-to';
+import useLoginHint from '@/hooks/use-login-hint';
+import usePreSignInErrorHandler from '@/hooks/use-pre-sign-in-error-handler';
+import useTerms from '@/hooks/use-terms';
+
+import ErrorPage from '../ErrorPage';
+import SwitchAccount from '../SwitchAccount';
+
+const OneTimeToken = () => {
+  const { token } = useParams();
+  const fallback = useFallbackRoute();
+  const email = useLoginHint();
+  const [mismatchedAccount, setMismatchedAccount] = useState<string>();
+  const [oneTimeTokenError, setOneTimeTokenError] = useState<unknown>();
+
+  const asyncRegisterWithOneTimeToken = useApi(identifyAndSubmitInteraction);
+  const asyncSignInWithVerifiedIdentifier = useApi(signInWithVerifiedIdentifier);
+  const asyncVerifyOneTimeToken = useApi(verifyOneTimeToken);
+
+  const { termsValidation, agreeToTermsPolicy } = useTerms();
+  const handleError = useErrorHandler();
+  const redirectTo = useGlobalRedirectTo();
+  const preSignInErrorHandler = usePreSignInErrorHandler();
+
+  const signInWithOneTimeToken = useCallback(
+    async (verificationId: string) => {
+      const [error, result] = await asyncSignInWithVerifiedIdentifier(verificationId);
+
+      if (error) {
+        await handleError(error, preSignInErrorHandler);
+        return;
+      }
+
+      if (result?.redirectTo) {
+        await redirectTo(result.redirectTo);
+      }
+    },
+    [preSignInErrorHandler, asyncSignInWithVerifiedIdentifier, handleError, redirectTo]
+  );
+
+  const registerWithOneTimeToken = useCallback(
+    async (verificationId: string) => {
+      const [error, result] = await asyncRegisterWithOneTimeToken({ verificationId });
+
+      if (error) {
+        await handleError(error, {
+          'user.email_already_in_use': async () => {
+            await signInWithOneTimeToken(verificationId);
+          },
+        });
+        return;
+      }
+
+      if (result?.redirectTo) {
+        await redirectTo(result.redirectTo);
+      }
+    },
+    [asyncRegisterWithOneTimeToken, handleError, redirectTo, signInWithOneTimeToken]
+  );
+
+  useEffect(() => {
+    (async () => {
+      if (token && email) {
+        /**
+         * Check if the user has agreed to the terms and privacy policy before navigating to the 3rd-party social sign-in page
+         * when the policy is set to `Manual`
+         */
+        if (agreeToTermsPolicy === AgreeToTermsPolicy.Manual && !(await termsValidation())) {
+          return;
+        }
+        const [error, result] = await asyncVerifyOneTimeToken({
+          token,
+          identifier: { type: SignInIdentifier.Email, value: email },
+        });
+
+        if (error) {
+          await handleError(error, {
+            'one_time_token.email_mismatch': () => {
+              setMismatchedAccount(email);
+            },
+            'one_time_token.token_expired': () => {
+              setOneTimeTokenError(error);
+            },
+            'one_time_token.token_consumed': () => {
+              setOneTimeTokenError(error);
+            },
+            'one_time_token.token_revoked': () => {
+              setOneTimeTokenError(error);
+            },
+            'one_time_token.token_not_found': () => {
+              setOneTimeTokenError(error);
+            },
+          });
+          return;
+        }
+
+        if (!result?.verificationId) {
+          return;
+        }
+        await registerWithOneTimeToken(result.verificationId);
+      }
+
+      window.location.replace('/' + fallback);
+    })();
+  }, [
+    agreeToTermsPolicy,
+    email,
+    fallback,
+    token,
+    asyncVerifyOneTimeToken,
+    handleError,
+    registerWithOneTimeToken,
+    termsValidation,
+  ]);
+
+  if (mismatchedAccount) {
+    return <SwitchAccount account={mismatchedAccount} />;
+  }
+
+  if (oneTimeTokenError) {
+    return <ErrorPage title="error.invalid_link" message="error.invalid_link_description" />;
+  }
+
+  return <LoadingLayer />;
+};
+export default OneTimeToken;

packages/schemas/src/consts/experience.ts

@@ -6,6 +6,8 @@ const routes = Object.freeze({
   resetPassword: 'reset-password',
   identifierSignIn: 'identifier-sign-in',
   identifierRegister: 'identifier-register',
+  switchAccount: 'switch-account',
+  error: 'error',
 } as const);
 
 export const experience = Object.freeze({