feat(api): implement authorization code flow in the new api (#55413)

2026-05-28 18:26:54 +00:00 · 2024-07-24 19:08:10 +02:00
parent 302d2b9f60
commit e94080add5
15 changed files with 858 additions and 81 deletions
@@ -9,6 +9,7 @@
    "@fastify/cookie": "9.4.0",
    "@fastify/csrf-protection": "6.4.1",
    "@fastify/express": "^2.3.0",
+    "@fastify/oauth2": "7.8.1",
    "@fastify/swagger": "8.14.0",
    "@fastify/swagger-ui": "1.10.2",
    "@fastify/type-provider-typebox": "3.6.0",
@@ -26,7 +26,7 @@ import redirectWithMessage from './plugins/redirect-with-message';
 import security from './plugins/security';
 import codeFlowAuth from './plugins/code-flow-auth';
 import notFound from './plugins/not-found';
-import { mobileAuth0Routes } from './routes/auth';
+import { authRoutes, mobileAuth0Routes } from './routes/auth';
 import { devAuthRoutes } from './routes/auth-dev';
 import {
  protectedCertificateRoutes,
@@ -40,6 +40,7 @@ import { emailSubscribtionRoutes } from './routes/email-subscription';
 import { settingRoutes, settingRedirectRoutes } from './routes/settings';
 import { statusRoute } from './routes/status';
 import { userGetRoutes, userRoutes, userPublicGetRoutes } from './routes/user';
+import { signoutRoute } from './routes/signout';
 import {
  API_LOCATION,
  EMAIL_PROVIDER,
@@ -220,10 +221,14 @@ export const build = async (

  // Routes not requiring authentication
  void fastify.register(mobileAuth0Routes);
+  // TODO: consolidate with LOCAL_MOCK_AUTH
  if (FCC_ENABLE_DEV_LOGIN_MODE) {
    void fastify.register(devAuthRoutes);
+  } else {
+    void fastify.register(authRoutes);
  }
  void fastify.register(chargeStripeRoute);
+  void fastify.register(signoutRoute);
  void fastify.register(emailSubscribtionRoutes);
  void fastify.register(userPublicGetRoutes);
  void fastify.register(unprotectedCertificateRoutes);
@@ -0,0 +1,405 @@
+const COOKIE_DOMAIN = 'test.com';
+import Fastify, { FastifyInstance } from 'fastify';
+
+import { createUserInput, nanoidCharSet } from '../utils/create-user';
+import { AUTH0_DOMAIN, HOME_LOCATION } from '../utils/env';
+import prismaPlugin from '../db/prisma';
+import cookies, { sign, unsign } from './cookies';
+import { auth0Client } from './auth0';
+import redirectWithMessage, { formatMessage } from './redirect-with-message';
+import codeFlowAuth from './code-flow-auth';
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+jest.mock('../utils/env', () => ({
+  ...jest.requireActual('../utils/env'),
+  COOKIE_DOMAIN
+}));
+
+describe('auth0 plugin', () => {
+  let fastify: FastifyInstance;
+
+  beforeAll(async () => {
+    fastify = Fastify();
+
+    await fastify.register(cookies);
+    await fastify.register(redirectWithMessage);
+    await fastify.register(codeFlowAuth);
+    await fastify.register(auth0Client);
+    await fastify.register(prismaPlugin);
+  });
+
+  afterAll(async () => {
+    await fastify.close();
+  });
+
+  describe('GET /signin', () => {
+    it('should redirect to the auth0 login page', async () => {
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/signin'
+      });
+
+      const redirectUrl = new URL(res.headers.location!);
+      expect(redirectUrl.host).toMatch(AUTH0_DOMAIN);
+      expect(redirectUrl.pathname).toBe('/authorize');
+      expect(res.statusCode).toBe(302);
+    });
+
+    it('sets a login-returnto cookie', async () => {
+      const returnTo = 'http://localhost:3000/learn';
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/signin',
+        headers: {
+          referer: returnTo
+        }
+      });
+
+      const cookie = res.cookies.find(c => c.name === 'login-returnto');
+      expect(unsign(cookie!.value).value).toBe(returnTo);
+      expect(cookie).toMatchObject({
+        domain: COOKIE_DOMAIN,
+        httpOnly: true,
+        secure: true,
+        sameSite: 'Lax'
+      });
+    });
+  });
+
+  describe('GET /auth/auth0/callback', () => {
+    const email = 'new@user.com';
+    let getAccessTokenFromAuthorizationCodeFlowSpy: jest.SpyInstance;
+    let userinfoSpy: jest.SpyInstance;
+
+    const mockAuthSuccess = () => {
+      getAccessTokenFromAuthorizationCodeFlowSpy.mockResolvedValueOnce({
+        token: 'any token'
+      });
+      userinfoSpy.mockResolvedValueOnce(Promise.resolve({ email }));
+    };
+
+    beforeEach(() => {
+      getAccessTokenFromAuthorizationCodeFlowSpy = jest.spyOn(
+        fastify.auth0OAuth,
+        'getAccessTokenFromAuthorizationCodeFlow'
+      );
+      userinfoSpy = jest.spyOn(fastify.auth0OAuth, 'userinfo');
+      // @ts-expect-error - Only mocks part of the Sentry object.
+      fastify.Sentry = { captureException: () => '' };
+    });
+
+    afterEach(async () => {
+      jest.restoreAllMocks();
+      await fastify.prisma.user.deleteMany({ where: { email } });
+    });
+
+    it('should redirect to the client if authentication fails', async () => {
+      getAccessTokenFromAuthorizationCodeFlowSpy.mockRejectedValueOnce(
+        'any error'
+      );
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback'
+      });
+
+      expect(res.headers.location).toMatch(
+        `${HOME_LOCATION}/learn?${formatMessage({ type: 'danger', content: 'flash.generic-error' })}`
+      );
+      expect(res.statusCode).toBe(302);
+    });
+
+    it('should redirect to the client if the state is invalid', async () => {
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=invalid'
+      });
+
+      expect(res.headers.location).toMatch(
+        `${HOME_LOCATION}/learn?${formatMessage({ type: 'danger', content: 'flash.generic-error' })}`
+      );
+      expect(res.statusCode).toBe(302);
+    });
+
+    it('should log an error if the state is invalid', async () => {
+      jest.spyOn(fastify.log, 'error');
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=invalid'
+      });
+
+      expect(fastify.log.error).toHaveBeenCalledWith(
+        'Auth failed: invalid state'
+      );
+      expect(res.statusCode).toBe(302);
+    });
+
+    it('should not create a user if the state is invalid', async () => {
+      await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=invalid'
+      });
+
+      expect(await fastify.prisma.user.count()).toBe(0);
+    });
+
+    it('should block requests with "access_denied" error', async () => {
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?error=access_denied&error_description=Access denied from your location'
+      });
+
+      expect(res.statusCode).toBe(302);
+      expect(res.headers.location).toMatch(`${HOME_LOCATION}/blocked`);
+
+      const resWithoutDescription = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?error=access_denied'
+      });
+
+      expect(resWithoutDescription.statusCode).toBe(302);
+      expect(resWithoutDescription.headers.location).toMatch(
+        `${HOME_LOCATION}/learn?messages=`
+      );
+    });
+
+    it('creates a user if the state is valid', async () => {
+      mockAuthSuccess();
+      await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid'
+      });
+
+      expect(await fastify.prisma.user.count()).toBe(1);
+    });
+
+    it('handles userinfo errors', async () => {
+      getAccessTokenFromAuthorizationCodeFlowSpy.mockResolvedValueOnce({
+        token: 'any token'
+      });
+      userinfoSpy.mockResolvedValueOnce(Promise.reject('any error'));
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid'
+      });
+
+      expect(res.headers.location).toMatch('/signin');
+      expect(res.statusCode).toBe(302);
+      expect(await fastify.prisma.user.count()).toBe(0);
+    });
+
+    it('handles invalid userinfo responses', async () => {
+      getAccessTokenFromAuthorizationCodeFlowSpy.mockResolvedValueOnce({
+        token: 'any token'
+      });
+      userinfoSpy.mockResolvedValueOnce(Promise.resolve({}));
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid'
+      });
+
+      expect(res.headers.location).toMatch('/signin');
+      expect(res.statusCode).toBe(302);
+      expect(await fastify.prisma.user.count()).toBe(0);
+    });
+
+    it('redirects with the signin-success message on success', async () => {
+      mockAuthSuccess();
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid'
+      });
+
+      expect(res.headers.location).toMatch(
+        `?${formatMessage({ type: 'success', content: 'flash.signin-success' })}`
+      );
+      expect(res.statusCode).toBe(302);
+    });
+
+    it('should set the jwt_access_token cookie', async () => {
+      mockAuthSuccess();
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid'
+      });
+
+      expect(res.headers['set-cookie']).toEqual(
+        expect.stringMatching(/jwt_access_token=/)
+      );
+    });
+
+    it('should use the login-returnto cookie if present and valid', async () => {
+      mockAuthSuccess();
+      await fastify.prisma.user.create({
+        data: { ...createUserInput(email), acceptedPrivacyTerms: true }
+      });
+      const returnTo = 'https://www.freecodecamp.org/espanol/learn';
+      // /signin sets the cookie
+      const req = await fastify.inject({
+        method: 'GET',
+        url: '/signin',
+        headers: {
+          referer: returnTo
+        }
+      });
+      const returnToCookie = req.cookies.find(c => c.name === 'login-returnto');
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid',
+        cookies: { 'login-returnto': returnToCookie!.value }
+      });
+
+      expect(res.headers.location).toBe(
+        `${returnTo}?${formatMessage({ type: 'success', content: 'flash.signin-success' })}`
+      );
+    });
+
+    it('should redirect home if the login-returnto cookie is invalid', async () => {
+      mockAuthSuccess();
+      const returnTo = 'https://www.evilcodecamp.org/espanol/learn';
+      // /signin sets the cookie
+      const req = await fastify.inject({
+        method: 'GET',
+        url: '/signin',
+        headers: {
+          referer: returnTo
+        }
+      });
+      const returnToCookie = req.cookies.find(c => c.name === 'login-returnto');
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid',
+        cookies: { 'login-returnto': returnToCookie!.value }
+      });
+
+      expect(res.headers.location).toMatch(HOME_LOCATION);
+    });
+
+    it('should redirect to email-sign-up if the user has not acceptedPrivacyTerms', async () => {
+      mockAuthSuccess();
+      // Using an italian path to make sure redirection works.
+      const italianReturnTo = 'https://www.freecodecamp.org/italian/settings';
+
+      const res = await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid',
+        cookies: {
+          'login-returnto': sign(italianReturnTo)
+        }
+      });
+
+      expect(res.headers.location).toEqual(
+        expect.stringContaining(
+          'https://www.freecodecamp.org/italian/email-sign-up?'
+        )
+      );
+    });
+
+    it('should populate the user with the correct data', async () => {
+      mockAuthSuccess();
+      const uuidRe = /^[a-f0-9]{8}-([a-f0-9]{4}-){3}[a-f0-9]{12}$/;
+      const fccUuidRe = /^fcc-[a-f0-9]{8}-([a-f0-9]{4}-){3}[a-f0-9]{12}$/;
+      const unsubscribeIdRe = new RegExp(`^[${nanoidCharSet}]{21}$`);
+      const mongodbIdRe = /^[a-f0-9]{24}$/;
+
+      await fastify.inject({
+        method: 'GET',
+        url: '/auth/auth0/callback?state=valid'
+      });
+
+      const user = await fastify.prisma.user.findFirstOrThrow({
+        where: { email }
+      });
+
+      expect(user).toEqual({
+        about: '',
+        acceptedPrivacyTerms: false,
+        completedChallenges: [],
+        completedExams: [],
+        currentChallengeId: '',
+        donationEmails: [],
+        email,
+        emailAuthLinkTTL: null,
+        emailVerified: true,
+        emailVerifyTTL: null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        externalId: expect.stringMatching(uuidRe),
+        githubProfile: null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        id: expect.stringMatching(mongodbIdRe),
+        is2018DataVisCert: false,
+        is2018FullStackCert: false,
+        isApisMicroservicesCert: false,
+        isBackEndCert: false,
+        isBanned: false,
+        isCheater: false,
+        isClassroomAccount: null,
+        isDataAnalysisPyCertV7: false,
+        isDataVisCert: false,
+        isDonating: false,
+        isFoundationalCSharpCertV8: false,
+        isFrontEndCert: false,
+        isFrontEndLibsCert: false,
+        isFullStackCert: false,
+        isHonest: false,
+        isInfosecCertV7: false,
+        isInfosecQaCert: false,
+        isJsAlgoDataStructCert: false,
+        isJsAlgoDataStructCertV8: false,
+        isMachineLearningPyCertV7: false,
+        isQaCertV7: false,
+        isRelationalDatabaseCertV8: false,
+        isCollegeAlgebraPyCertV8: false,
+        isRespWebDesignCert: false,
+        isSciCompPyCertV7: false,
+        isUpcomingPythonCertV8: null,
+        keyboardShortcuts: false,
+        linkedin: null,
+        location: '',
+        name: '',
+        needsModeration: false,
+        newEmail: null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        unsubscribeId: expect.stringMatching(unsubscribeIdRe),
+        partiallyCompletedChallenges: [],
+        password: null,
+        picture: '',
+        portfolio: [],
+        profileUI: {
+          isLocked: false,
+          showAbout: false,
+          showCerts: false,
+          showDonation: false,
+          showHeatMap: false,
+          showLocation: false,
+          showName: false,
+          showPoints: false,
+          showPortfolio: false,
+          showTimeLine: false
+        },
+        progressTimestamps: [expect.any(Number)],
+        rand: null,
+        savedChallenges: [],
+        sendQuincyEmail: false,
+        theme: 'default',
+        timezone: null,
+        twitter: null,
+        updateCount: 0,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        username: expect.stringMatching(fccUuidRe),
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        usernameDisplay: expect.stringMatching(fccUuidRe),
+        verificationToken: null,
+        website: null,
+        yearsTopContributor: []
+      });
+      expect(user.username).toBe(user.usernameDisplay);
+    });
+  });
+});
@@ -0,0 +1,155 @@
+import fastifyOauth2, { type OAuth2Namespace } from '@fastify/oauth2';
+import { type FastifyPluginCallbackTypebox } from '@fastify/type-provider-typebox';
+import fp from 'fastify-plugin';
+
+import {
+  API_LOCATION,
+  AUTH0_CLIENT_ID,
+  AUTH0_CLIENT_SECRET,
+  AUTH0_DOMAIN,
+  COOKIE_DOMAIN,
+  HOME_LOCATION
+} from '../utils/env';
+import { findOrCreateUser } from '../routes/helpers/auth-helpers';
+import { createAccessToken } from '../utils/tokens';
+import {
+  getLoginRedirectParams,
+  getPrefixedLandingPath
+} from '../utils/redirection';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    auth0OAuth: OAuth2Namespace;
+  }
+}
+
+/**
+ * Fastify plugin for Auth0 authentication. This uses fastify-plugin to expose
+ * the auth0OAuth decorator (for easier testing), but to maintain encapsulation
+ * it should be registered in a plugin. That prevents auth0OAuth from being
+ * available globally.
+ *
+ * @param fastify - The Fastify instance.
+ * @param _options - The plugin options.
+ * @param done - The callback function.
+ */
+export const auth0Client: FastifyPluginCallbackTypebox = fp(
+  (fastify, _options, done) => {
+    void fastify.register(fastifyOauth2, {
+      name: 'auth0OAuth',
+      scope: ['openid', 'email', 'profile'],
+      credentials: {
+        client: {
+          id: AUTH0_CLIENT_ID,
+          secret: AUTH0_CLIENT_SECRET
+        }
+      },
+      discovery: { issuer: `https://${AUTH0_DOMAIN}` },
+      callbackUri: `${API_LOCATION}/auth/auth0/callback`,
+      cookie: {
+        // It's important not to sign the cookie, since the OAuth2 plugin will
+        // not unsign it.
+        signed: false
+      }
+    });
+
+    fastify.get('/signin', async function (request, reply) {
+      const returnTo = request.headers.referer ?? `${HOME_LOCATION}/learn`;
+      void reply.setCookie('login-returnto', returnTo, {
+        domain: COOKIE_DOMAIN,
+        httpOnly: true,
+        secure: true,
+        signed: true,
+        sameSite: 'lax'
+      });
+
+      const redirectUrl = await this.auth0OAuth.generateAuthorizationUri(
+        request,
+        reply
+      );
+      void reply.redirect(redirectUrl);
+    });
+
+    // TODO: use a schema to validate the query params.
+    fastify.get('/auth/auth0/callback', async function (request, reply) {
+      const { error, error_description } = request.query as Record<
+        string,
+        string
+      >;
+      if (error === 'access_denied') {
+        const blockedByLaw =
+          error_description === 'Access denied from your location';
+
+        if (blockedByLaw) {
+          return reply.redirect(`${HOME_LOCATION}/blocked`);
+        } else {
+          return reply.redirectWithMessage(`${HOME_LOCATION}/learn`, {
+            type: 'info',
+            content: error_description ?? 'Authentication failed'
+          });
+        }
+      }
+
+      const { returnTo, pathPrefix, origin } = getLoginRedirectParams(request);
+      const redirectBase = getPrefixedLandingPath(origin, pathPrefix);
+
+      let token;
+      try {
+        token = (
+          await this.auth0OAuth.getAccessTokenFromAuthorizationCodeFlow(request)
+        ).token;
+      } catch (error) {
+        // This is the plugin's error message. If it changes, we will either
+        // have to update the test or write custom state create/verify
+        // functions.
+        if (error instanceof Error && error.message === 'Invalid state') {
+          fastify.log.error('Auth failed: invalid state');
+        } else {
+          fastify.log.error('Auth failed', error);
+          fastify.Sentry.captureException(error);
+        }
+        // It's important _not_ to redirect to /signin here, as that could
+        // create an infinite loop.
+        return reply.redirectWithMessage(returnTo, {
+          type: 'danger',
+          content: 'flash.generic-error'
+        });
+      }
+
+      let email;
+      try {
+        const userinfo = (await fastify.auth0OAuth.userinfo(token)) as {
+          email: string;
+        };
+        email = userinfo.email;
+        if (typeof email !== 'string') throw Error('Invalid userinfo response');
+      } catch (error) {
+        fastify.log.error('Auth failed', error);
+        fastify.Sentry.captureException(error);
+        return reply.redirect('/signin');
+      }
+
+      const { id, acceptedPrivacyTerms } = await findOrCreateUser(
+        fastify,
+        email
+      );
+
+      reply.setAccessTokenCookie(createAccessToken(id));
+
+      if (acceptedPrivacyTerms) {
+        void reply.redirectWithMessage(returnTo, {
+          type: 'success',
+          content: 'flash.signin-success'
+        });
+      } else {
+        void reply.redirectWithMessage(`${redirectBase}/email-sign-up`, {
+          type: 'success',
+          content: 'flash.signin-success'
+        });
+      }
+    });
+
+    done();
+  },
+  { dependencies: ['redirect-with-message'] }
+);
@@ -1,11 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
-import {
-  defaultUserEmail,
-  devLogin,
-  setupServer,
-  superRequest
-} from '../../jest.utils';
+import { defaultUserEmail, setupServer, superRequest } from '../../jest.utils';
 import { HOME_LOCATION } from '../utils/env';
 import { nanoidCharSet } from '../utils/create-user';

@@ -41,6 +36,7 @@ describe('dev login', () => {
      const uuidRe = /^[a-f0-9]{8}-([a-f0-9]{4}-){3}[a-f0-9]{12}$/;
      const fccUuidRe = /^fcc-[a-f0-9]{8}-([a-f0-9]{4}-){3}[a-f0-9]{12}$/;
      const unsubscribeIdRe = new RegExp(`^[${nanoidCharSet}]{21}$`);
+      const mongodbIdRe = /^[a-f0-9]{24}$/;

      await superRequest('/signin', { method: 'GET' });
      const user = await fastifyTestInstance.prisma.user.findFirstOrThrow({
@@ -51,19 +47,29 @@ describe('dev login', () => {
        about: '',
        acceptedPrivacyTerms: false,
        completedChallenges: [],
+        completedExams: [],
        currentChallengeId: '',
+        donationEmails: [],
        email: defaultUserEmail,
+        emailAuthLinkTTL: null,
        emailVerified: true,
+        emailVerifyTTL: null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
        externalId: expect.stringMatching(uuidRe),
+        githubProfile: null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        id: expect.stringMatching(mongodbIdRe),
        is2018DataVisCert: false,
        is2018FullStackCert: false,
        isApisMicroservicesCert: false,
        isBackEndCert: false,
        isBanned: false,
        isCheater: false,
+        isClassroomAccount: null,
        isDataAnalysisPyCertV7: false,
        isDataVisCert: false,
        isDonating: false,
+        isFoundationalCSharpCertV8: false,
        isFrontEndCert: false,
        isFrontEndLibsCert: false,
        isFullStackCert: false,
@@ -71,17 +77,26 @@ describe('dev login', () => {
        isInfosecCertV7: false,
        isInfosecQaCert: false,
        isJsAlgoDataStructCert: false,
+        isJsAlgoDataStructCertV8: false,
        isMachineLearningPyCertV7: false,
        isQaCertV7: false,
        isRelationalDatabaseCertV8: false,
        isCollegeAlgebraPyCertV8: false,
        isRespWebDesignCert: false,
        isSciCompPyCertV7: false,
+        isUpcomingPythonCertV8: null,
        keyboardShortcuts: false,
+        linkedin: null,
        location: '',
        name: '',
+        needsModeration: false,
+        newEmail: null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
        unsubscribeId: expect.stringMatching(unsubscribeIdRe),
+        partiallyCompletedChallenges: [],
+        password: null,
        picture: '',
+        portfolio: [],
        profileUI: {
          isLocked: false,
          showAbout: false,
@@ -95,10 +110,18 @@ describe('dev login', () => {
          showTimeLine: false
        },
        progressTimestamps: [expect.any(Number)],
+        savedChallenges: [],
        sendQuincyEmail: false,
        theme: 'default',
+        timezone: null,
+        twitter: null,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
        username: expect.stringMatching(fccUuidRe),
-        usernameDisplay: expect.stringMatching(fccUuidRe)
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        usernameDisplay: expect.stringMatching(fccUuidRe),
+        verificationToken: null,
+        website: null,
+        yearsTopContributor: []
      });
      expect(user.username).toBe(user.usernameDisplay);
    });
@@ -169,39 +192,4 @@ describe('dev login', () => {
      expect(res.headers.location).toBe(`${HOME_LOCATION}/learn`);
    });
  });
-
-  describe('GET /signout', () => {
-    beforeEach(async () => {
-      await devLogin();
-    });
-    it('should clear all the cookies', async () => {
-      const res = await superRequest('/signout', { method: 'GET' });
-
-      const setCookie = res.headers['set-cookie'];
-      expect(setCookie).toEqual(
-        expect.arrayContaining([
-          expect.stringMatching(
-            /^jwt_access_token=; Path=\/; Expires=Thu, 01 Jan 1970 00:00:00 GMT/
-          ),
-          expect.stringMatching(
-            /^csrf_token=; Path=\/; Expires=Thu, 01 Jan 1970 00:00:00 GMT/
-          ),
-          expect.stringMatching(
-            /^_csrf=; Path=\/; Expires=Thu, 01 Jan 1970 00:00:00 GMT/
-          )
-        ])
-      );
-      expect(setCookie).toHaveLength(3);
-    });
-
-    it('should redirect to / on the client by default', async () => {
-      const res = await superRequest('/signout', { method: 'GET' });
-
-      // This happens because localhost:8000 is not an allowed origin and so
-      // normalizeParams rejects it and sets the returnTo to /learn. TODO:
-      // separate the validation and normalization logic.
-      expect(res.headers.location).toBe(`${HOME_LOCATION}/learn`);
-      expect(res.status).toBe(302);
-    });
-  });
 });
@@ -46,11 +46,5 @@ export const devAuthRoutes: FastifyPluginCallback = (
    await handleRedirects(req, reply);
  });

-  fastify.get('/signout', async (req, reply) => {
-    reply.clearOurCookies();
-
-    const { returnTo } = getRedirectParams(req);
-    await reply.redirect(returnTo);
-  });
  done();
 };
@@ -0,0 +1,32 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+import { createSuperRequest, devLogin, setupServer } from '../../jest.utils';
+import { AUTH0_DOMAIN } from '../utils/env';
+
+jest.mock('../utils/env', () => {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  return {
+    ...jest.requireActual('../utils/env'),
+    FCC_ENABLE_DEV_LOGIN_MODE: false
+  };
+});
+
+describe('auth0 routes', () => {
+  setupServer();
+  describe('GET /signin', () => {
+    let superGet: ReturnType<typeof createSuperRequest>;
+    beforeAll(async () => {
+      const setCookies = await devLogin();
+
+      superGet = createSuperRequest({ method: 'GET', setCookies });
+    });
+    it('should redirect to the auth0 login page', async () => {
+      const res = await superGet('/signin');
+
+      expect(res.status).toBe(302);
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      const redirectUrl = new URL(res.headers.location);
+      expect(redirectUrl.host).toMatch(AUTH0_DOMAIN);
+      expect(redirectUrl.pathname).toBe('/authorize');
+    });
+  });
+});
@@ -1,10 +1,10 @@
 import { FastifyPluginCallback, FastifyRequest } from 'fastify';
-
 import rateLimit from 'express-rate-limit';
 // @ts-expect-error - no types
 import MongoStoreRL from 'rate-limit-mongo';

 import { AUTH0_DOMAIN, MONGOHQ_URL } from '../utils/env';
+import { auth0Client } from '../plugins/auth0';
 import { findOrCreateUser } from './helpers/auth-helpers';

 const getEmailFromAuth0 = async (req: FastifyRequest) => {
@@ -63,3 +63,18 @@ export const mobileAuth0Routes: FastifyPluginCallback = (

  done();
 };
+
+/**
+ * Route handler for authentication routes.
+ *
+ * @param fastify The Fastify instance.
+ * @param _options Options passed to the plugin via `fastify.register(plugin, options)`.
+ * @param done Callback to signal that the logic has completed.
+ */
+export const authRoutes: FastifyPluginCallback = (fastify, _options, done) => {
+  // All routes are registered by the auth0 plugin, but we need an extra plugin
+  // (this one) to encapsulate the auth0 decorators. Otherwise auth0OAuth will
+  // be available globally.
+  void fastify.register(auth0Client);
+  done();
+};
@@ -10,12 +10,12 @@ import { createUserInput } from '../../utils/create-user';
 export const findOrCreateUser = async (
  fastify: FastifyInstance,
  email: string
-): Promise<{ id: string }> => {
+): Promise<{ id: string; acceptedPrivacyTerms: boolean }> => {
  // TODO: handle the case where there are multiple users with the same email.
  // e.g. use findMany and throw an error if more than one is found.
  const existingUser = await fastify.prisma.user.findMany({
    where: { email },
-    select: { id: true }
+    select: { id: true, acceptedPrivacyTerms: true }
  });
  if (existingUser.length > 1) {
    fastify.Sentry.captureException(
@@ -27,7 +27,7 @@ export const findOrCreateUser = async (
    existingUser[0] ??
    (await fastify.prisma.user.create({
      data: createUserInput(email),
-      select: { id: true }
+      select: { id: true, acceptedPrivacyTerms: true }
    }))
  );
 };
@@ -0,0 +1,41 @@
+import { devLogin, setupServer, superRequest } from '../../jest.utils';
+import { HOME_LOCATION } from '../utils/env';
+
+describe('GET /signout', () => {
+  setupServer();
+
+  beforeEach(async () => {
+    await devLogin();
+  });
+  it('should clear all the cookies', async () => {
+    const res = await superRequest('/signout', { method: 'GET' });
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+    const setCookie = res.headers['set-cookie'];
+    expect(setCookie).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(
+          /^jwt_access_token=; Path=\/; Expires=Thu, 01 Jan 1970 00:00:00 GMT/
+        ),
+        expect.stringMatching(
+          /^csrf_token=; Path=\/; Expires=Thu, 01 Jan 1970 00:00:00 GMT/
+        ),
+        expect.stringMatching(
+          /^_csrf=; Path=\/; Expires=Thu, 01 Jan 1970 00:00:00 GMT/
+        )
+      ])
+    );
+    expect(setCookie).toHaveLength(3);
+  });
+
+  it('should redirect to / on the client by default', async () => {
+    const res = await superRequest('/signout', { method: 'GET' });
+
+    // This happens because localhost:8000 is not an allowed origin and so
+    // normalizeParams rejects it and sets the returnTo to /learn. TODO:
+    // separate the validation and normalization logic.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    expect(res.headers.location).toBe(`${HOME_LOCATION}/learn`);
+    expect(res.status).toBe(302);
+  });
+});
@@ -0,0 +1,27 @@
+import type { FastifyPluginCallback } from 'fastify';
+
+import { getRedirectParams } from '../utils/redirection';
+
+/**
+ * Route handler for signing out.
+ *
+ * @param fastify The Fastify instance.
+ * @param _options Options passed to the plugin via `fastify.register(plugin,
+ * options)`.
+ * @param done Callback to signal that the logic has completed.
+ */
+export const signoutRoute: FastifyPluginCallback = (
+  fastify,
+  _options,
+  done
+) => {
+  fastify.get('/signout', async (req, reply) => {
+    void reply.clearCookie('jwt_access_token');
+    void reply.clearCookie('csrf_token');
+    void reply.clearCookie('_csrf');
+
+    const { returnTo } = getRedirectParams(req);
+    await reply.redirect(returnTo);
+  });
+  done();
+};
@@ -45,6 +45,8 @@ assert.ok(process.env.FREECODECAMP_NODE_ENV);
 assert.ok(isAllowedEnv(process.env.FREECODECAMP_NODE_ENV));
 assert.ok(process.env.EMAIL_PROVIDER);
 assert.ok(isAllowedProvider(process.env.EMAIL_PROVIDER));
+assert.ok(process.env.AUTH0_CLIENT_ID);
+assert.ok(process.env.AUTH0_CLIENT_SECRET);
 assert.ok(process.env.AUTH0_DOMAIN);
 assert.ok(process.env.AUTH0_AUDIENCE);
 assert.ok(process.env.API_LOCATION);
@@ -96,6 +98,11 @@ if (process.env.FREECODECAMP_NODE_ENV !== 'development') {
    'The Stripe secret should be changed from the default value.'
  );
  assert.notEqual(process.env.NODE_ENV, 'test');
+  assert.notEqual(
+    process.env.AUTH0_CLIENT_SECRET,
+    'client_secret_from_auth0_dashboard',
+    'The Auth0 client secret should be changed from the default value.'
+  );
 }

 export const HOME_LOCATION = process.env.HOME_LOCATION;
@@ -109,8 +116,10 @@ export const MONGOHQ_URL =
    : process.env.MONGOHQ_URL;

 export const FREECODECAMP_NODE_ENV = process.env.FREECODECAMP_NODE_ENV;
+export const AUTH0_CLIENT_ID = process.env.AUTH0_CLIENT_ID;
 export const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN;
 export const AUTH0_AUDIENCE = process.env.AUTH0_AUDIENCE;
+export const AUTH0_CLIENT_SECRET = process.env.AUTH0_CLIENT_SECRET;
 export const PORT = process.env.PORT || '3000';
 export const HOST = process.env.HOST || 'localhost';
 export const API_LOCATION = process.env.API_LOCATION;
@@ -1,11 +1,11 @@
-import { FastifyRequest } from 'fastify';
 import jwt from 'jsonwebtoken';

 import {
  getReturnTo,
  normalizeParams,
  getRedirectParams,
-  getPrefixedLandingPath
+  getPrefixedLandingPath,
+  getLoginRedirectParams
 } from './redirection';
 import { HOME_LOCATION } from './env';

@@ -148,12 +148,12 @@ describe('redirection', () => {
  });

  describe('getRedirectParams', () => {
-    it('should decorate the request object', () => {
-      const req: FastifyRequest = {
+    it('should return origin, pathPrefix and returnTo given valid headers', () => {
+      const req = {
        headers: {
          referer: `https://www.freecodecamp.org/espanol/learn/rosetta-code/`
        }
-      } as FastifyRequest;
+      };

      const expectedReturn = {
        origin: 'https://www.freecodecamp.org',
@@ -166,9 +166,9 @@ describe('redirection', () => {
    });

    it('should use HOME_LOCATION with missing referer', () => {
-      const req: FastifyRequest = {
+      const req = {
        headers: {}
-      } as FastifyRequest;
+      };

      const expectedReturn = {
        returnTo: `${HOME_LOCATION}/learn`,
@@ -181,11 +181,11 @@ describe('redirection', () => {
    });

    it('should use HOME_LOCATION with invalid referrer', () => {
-      const req: FastifyRequest = {
+      const req = {
        headers: {
          referer: 'invalid-url'
        }
-      } as FastifyRequest;
+      };

      const expectedReturn = {
        returnTo: `${HOME_LOCATION}/learn`,
@@ -198,6 +198,26 @@ describe('redirection', () => {
    });
  });

+  describe('getLoginRedirectParams', () => {
+    it('should use the login-returnto cookie if present', () => {
+      const mockReq = {
+        cookies: {
+          'login-returnto': 'https://www.freecodecamp.org/espanol/learn'
+        },
+        unsignCookie: (rawValue: string) => ({ value: rawValue })
+      };
+
+      const expectedReturn = {
+        origin: 'https://www.freecodecamp.org',
+        pathPrefix: 'espanol',
+        returnTo: 'https://www.freecodecamp.org/espanol/learn'
+      };
+
+      const result = getLoginRedirectParams(mockReq);
+      expect(result).toEqual(expectedReturn);
+    });
+  });
+
  describe('getPrefixedLandingPath', () => {
    it('should return the origin when no pathPrefix is provided', () => {
      const result = getPrefixedLandingPath(defaultOrigin);
@@ -1,4 +1,3 @@
-import { FastifyRequest } from 'fastify';
 import jwt from 'jsonwebtoken';

 import { availableLangs } from '../../../shared/config/i18n';
@@ -39,6 +38,12 @@ export function getReturnTo(
  return normalizeParams(params, _homeLocation);
 }

+type RedirectParams = {
+  returnTo: string;
+  origin: string;
+  pathPrefix: string;
+};
+
 /**
 * Normalize the parameters, making they're valid.
 *
@@ -50,18 +55,16 @@ export function getReturnTo(
 * @returns The normalized parameters.
 */
 export function normalizeParams(
-  {
-    returnTo,
-    origin,
-    pathPrefix
-  }: { returnTo?: string; origin?: string; pathPrefix?: string },
+  { returnTo, origin, pathPrefix }: Partial<RedirectParams>,
  _homeLocation = HOME_LOCATION
-) {
+): RedirectParams {
  // coerce to strings, just in case something weird and nefarious is happening
  // TODO: validate, don't coerce
  returnTo = '' + returnTo;
  origin = '' + origin;
  pathPrefix = '' + pathPrefix;
+  // TODO(Post-MVP): consider adding HOME_LOCATION in allowedOrigins to allow
+  // redirection to work in development.
  // we add the '/' to prevent returns to
  // www.freecodecamp.org.somewhere.else.com
  if (
@@ -93,18 +96,10 @@ export function getPrefixedLandingPath(origin: string, pathPrefix?: string) {
  return `${origin}${redirectPathSegment}`;
 }

-/**
- * Get the redirect parameters.
- *
- * @param req - A fastify Request.
- * @param _normalizeParams - The function to normalize the parameters.
- * @returns The redirect parameters.
- */
-export function getRedirectParams(
-  req: FastifyRequest,
-  _normalizeParams = normalizeParams
+function getParamsFromUrl(
+  url: string | undefined | null,
+  normalize: typeof normalizeParams
 ) {
-  const url = req.headers['referer'];
  // since we do not always redirect the user back to the page they were on
  // we need client locale and origin to construct the redirect url.
  let returnUrl;
@@ -118,7 +113,45 @@ export function getRedirectParams(
  // if this is not one of the client languages, validation will convert
  // this to '' before it is used.
  const pathPrefix = returnUrl.pathname.split('/')[1] ?? '';
-  return _normalizeParams({ returnTo: returnUrl.href, origin, pathPrefix });
+  return normalize({ returnTo: returnUrl.href, origin, pathPrefix });
+}
+
+/**
+ * Get the redirect parameters.
+ *
+ * @param req - A fastify Request.
+ * @param req.headers - The request headers.
+ * @param req.headers.referer - The referer header.
+ * @param _normalizeParams - The function to normalize the parameters.
+ * @returns The redirect parameters.
+ */
+export function getRedirectParams(
+  req: { headers: { referer?: string } },
+  _normalizeParams = normalizeParams
+): RedirectParams {
+  const url = req.headers['referer'];
+  return getParamsFromUrl(url, _normalizeParams);
+}
+
+/**
+ * Get the redirect parameters after sign in flow.
+ *
+ * @param req - A fastify Request.
+ * @param req.cookies - The request cookies.
+ * @param req.unsignCookie - The function to unsign the cookie.
+ * @param _normalizeParams - The function to normalize the parameters.
+ * @returns The redirect parameters.
+ */
+export function getLoginRedirectParams(
+  req: {
+    cookies: Record<string, string | undefined>;
+    unsignCookie: (rawValue: string) => { value: string | null };
+  },
+  _normalizeParams = normalizeParams
+): RedirectParams {
+  const signedUrl = req.cookies['login-returnto'];
+  const url = signedUrl ? req.unsignCookie(signedUrl).value : null;
+  return getParamsFromUrl(url, _normalizeParams);
 }

 /**
@@ -165,6 +165,9 @@ importers:
      '@fastify/express':
        specifier: ^2.3.0
        version: 2.3.0
+      '@fastify/oauth2':
+        specifier: 7.8.1
+        version: 7.8.1
      '@fastify/swagger':
        specifier: 8.14.0
        version: 8.14.0
@@ -2992,6 +2995,9 @@ packages:
  '@fastify/fast-json-stringify-compiler@4.3.0':
    resolution: {integrity: sha512-aZAXGYo6m22Fk1zZzEUKBvut/CIIQe/BapEORnxiD5Qr0kPHqqI69NtEMCme74h+at72sPhbkb4ZrLd1W3KRLA==}

+  '@fastify/oauth2@7.8.1':
+    resolution: {integrity: sha512-PBIMizzgEOcUcttyfX1hC6CR9vESoI1lfNucBywgcqrxvknVg+zvBCgH2+oU8NvrpSDMtlY6nyuEYYZtVhDT7Q==}
+
  '@fastify/send@2.1.0':
    resolution: {integrity: sha512-yNYiY6sDkexoJR0D8IDy3aRP3+L4wdqCpvx5WP+VtEU58sn7USmKynBzDQex5X42Zzvw2gNzzYgP90UfWShLFA==}

@@ -3157,10 +3163,19 @@ packages:
    resolution: {integrity: sha512-QD1PhQk+s31P1ixsX0H0Suoupp3VMXzIVMSwobR3F3MSUO2YCV0B7xqLcUw/Bh8yuvd3LhpyqLQWTNcRmp6IdQ==}
    deprecated: Moved to 'npm install @sideway/address'

+  '@hapi/boom@10.0.1':
+    resolution: {integrity: sha512-ERcCZaEjdH3OgSJlyjVk8pHIFeus91CjKP3v+MpgBNp5IvGzP2l/bRiD78nqYcKPaZdbKkK5vDBVPd2ohHBlsA==}
+
  '@hapi/bourne@1.3.2':
    resolution: {integrity: sha512-1dVNHT76Uu5N3eJNTYcvxee+jzX4Z9lfciqRRHCU27ihbUcYi+iSc2iml5Ke1LXe1SyJCLA0+14Jh4tXJgOppA==}
    deprecated: This version has been deprecated and is no longer supported or maintained

+  '@hapi/bourne@3.0.0':
+    resolution: {integrity: sha512-Waj1cwPXJDucOib4a3bAISsKJVb15MKi9IvmTI/7ssVEm6sywXGjVJDhl6/umt1pK1ZS7PacXU3A1PmFKHEZ2w==}
+
+  '@hapi/hoek@11.0.4':
+    resolution: {integrity: sha512-PnsP5d4q7289pS2T2EgGz147BFJ2Jpb4yrEdkpz2IhgEUzos1S7HTl7ezWh1yfYzYlj89KzLdCRkqsP6SIryeQ==}
+
  '@hapi/hoek@8.5.1':
    resolution: {integrity: sha512-yN7kbciD87WzLGc5539Tn0sApjyiGHAJgKvG9W8C7O+6c7qmoQMfVs0W4bX17eqz6C78QJqqFrtgdK5EWf6Qow==}
    deprecated: This version has been deprecated and is no longer supported or maintained
@@ -3179,6 +3194,9 @@ packages:
  '@hapi/topo@5.1.0':
    resolution: {integrity: sha512-foQZKJig7Ob0BMAYBfcJk8d77QtOe7Wo4ox7ff1lQYoNNAb6jwcY1ncdoy2e9wQZzvNy7ODZCYJkK8kzmcAnAg==}

+  '@hapi/wreck@18.1.0':
+    resolution: {integrity: sha512-0z6ZRCmFEfV/MQqkQomJ7sl/hyxvcZM7LtuVqN3vdAO4vM9eBbowl0kaqQj9EJJQab+3Uuh1GxbGIBFy4NfJ4w==}
+
  '@headlessui/react@1.7.19':
    resolution: {integrity: sha512-Ll+8q3OlMJfJbAKM/+/Y2q6PPYbryqNTXDbryx7SXLIDamkF6iQFbriYHga0dY44PvDhvvBWCx1Xj4U5+G4hOw==}
    engines: {node: '>=10'}
@@ -12277,6 +12295,9 @@ packages:
  simple-get@4.0.1:
    resolution: {integrity: sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==}

+  simple-oauth2@5.1.0:
+    resolution: {integrity: sha512-gWDa38Ccm4MwlG5U7AlcJxPv3lvr80dU7ARJWrGdgvOKyzSj1gr3GBPN1rABTedAYvC/LsGYoFuFxwDBPtGEbw==}
+
  simple-swizzle@0.2.2:
    resolution: {integrity: sha512-JA//kQgZtbuY83m+xT+tXJkmJncGMTFT+C+g2h2R9uxkYIrE2yy9sgmcLhCnw57/WSD+Eh3J97FPEDFnbXnDUg==}

@@ -17123,6 +17144,14 @@ snapshots:
    dependencies:
      fast-json-stringify: 5.8.0

+  '@fastify/oauth2@7.8.1':
+    dependencies:
+      '@fastify/cookie': 9.4.0
+      fastify-plugin: 4.5.1
+      simple-oauth2: 5.1.0
+    transitivePeerDependencies:
+      - supports-color
+
  '@fastify/send@2.1.0':
    dependencies:
      '@lukeed/ms': 2.0.1
@@ -17375,8 +17404,16 @@ snapshots:

  '@hapi/address@2.1.4': {}

+  '@hapi/boom@10.0.1':
+    dependencies:
+      '@hapi/hoek': 11.0.4
+
  '@hapi/bourne@1.3.2': {}

+  '@hapi/bourne@3.0.0': {}
+
+  '@hapi/hoek@11.0.4': {}
+
  '@hapi/hoek@8.5.1': {}

  '@hapi/hoek@9.3.0': {}
@@ -17396,6 +17433,12 @@ snapshots:
    dependencies:
      '@hapi/hoek': 9.3.0

+  '@hapi/wreck@18.1.0':
+    dependencies:
+      '@hapi/boom': 10.0.1
+      '@hapi/bourne': 3.0.0
+      '@hapi/hoek': 11.0.4
+
  '@headlessui/react@1.7.19(react-dom@16.14.0(react@16.14.0))(react@16.14.0)':
    dependencies:
      '@tanstack/react-virtual': 3.0.4(react-dom@16.14.0(react@16.14.0))(react@16.14.0)
@@ -29617,6 +29660,15 @@ snapshots:
      once: 1.4.0
      simple-concat: 1.0.1

+  simple-oauth2@5.1.0:
+    dependencies:
+      '@hapi/hoek': 11.0.4
+      '@hapi/wreck': 18.1.0
+      debug: 4.3.4(supports-color@8.1.1)
+      joi: 17.12.2
+    transitivePeerDependencies:
+      - supports-color
+
  simple-swizzle@0.2.2:
    dependencies:
      is-arrayish: 0.3.2