Authentication System Overhaul PR (#1607)

Author: technoplato

App.tsx

@@ -50,6 +50,7 @@ import {
 import logger from "./utils/logger";
 import { AuthenticateWithPasskeyProvider } from "./features/onboarding/contexts/signup-with-passkey.context";
 import { PrivyPlaygroundLandingScreen } from "./features/privy-playground/privy-playground-landing.screen";
+import { useLogoutOnJwtRefreshError } from "./features/authentication/useLogoutOnJwtRefreshError";
 // import { useAccountsStore } from "./features/multi-inbox/multi-inbox.store";
 // import { AuthenticateWithPasskeyProvider } from "./features/onboarding/contexts/signup-with-passkey.context";
 // import { PrivyPlaygroundLandingScreen } from "./features/privy-playground/privy-playground-landing.screen";
@@ -120,6 +121,7 @@ const coinbaseUrl = new URL(`https://${config.websiteDomain}/coinbase`);
 const App = () => {
   const styles = useStyles();
   const debugRef = useRef();
+  useLogoutOnJwtRefreshError();
 
   useEffect(() => {
     setupAppAttest();

config/config.types.ts

@@ -53,4 +53,5 @@ export type IConfig = {
   privy: IPrivyConfig;
   evm: IEvmConfig;
   appCheckDebugToken?: string;
+  reactQueryEncryptionKey: string;
 };

config/index.ts

@@ -2,6 +2,23 @@ import { isDev, isPreview } from "@/utils/getEnv";
 import { developmentConfig } from "./development";
 import { productionConfig } from "./production";
 import { previewConfig } from "./preview";
+import { z } from "zod";
+
+// todo: use zod for env and stop typing in multiple places
+// crash on first build step rather than at runtime
+// const configSchema = z.object({
+//   // ... other config variables ...
+//   SECURE_QUERY_ENCRYPTION_KEY: z.string().min(16),
+// });
+
+// // export const Config = {
+// //   // ... other config variables ...
+// //   SECURE_QUERY_ENCRYPTION_KEY: process.env
+// //     .SECURE_QUERY_ENCRYPTION_KEY as string,
+// // } satisfies z.infer<typeof configSchema>;
+
+// // // Validate config at startup
+// // configSchema.parse(Config);
 
 export const getConfig = () => {
   if (isDev) return developmentConfig;

config/shared.ts

@@ -57,4 +57,7 @@ export const shared = {
     clientId: process.env.EXPO_PUBLIC_PRIVY_CLIENT_ID,
   },
   thirdwebClientId: process.env.EXPO_PUBLIC_THIRDWEB_CLIENT_ID,
+  reactQueryEncryptionKey:
+    // @ts-expect-error todo fixme
+    process.env.EXPO_PUBLIC_SECURE_REACT_QUERY_ENCRYPTION_KEY,
 } as const satisfies Partial<IConfig>;

features/authentication/authentication.api.ts

@@ -0,0 +1,71 @@
+import { Platform } from "react-native";
+import * as Device from "expo-device";
+import { api } from "@/utils/api/api";
+import { z } from "zod";
+
+const deviceOSEnum = z.enum(["android", "ios", "web"]);
+
+const createUserResponseSchema = z.object({
+  id: z.string(),
+  privyUserId: z.string(),
+  device: z.object({
+    id: z.string(),
+    os: deviceOSEnum,
+    name: z.string().nullable(),
+  }),
+  identity: z.object({
+    id: z.string(),
+    privyAddress: z.string(),
+    xmtpId: z.string().nullable(),
+  }),
+  profile: z
+    .object({
+      id: z.string(),
+      name: z.string(),
+      description: z.string().nullable(),
+    })
+    .nullable(),
+});
+
+type CreateUserResponse = z.infer<typeof createUserResponseSchema>;
+
+export const createUser = async (args: {
+  privyUserId: string;
+  smartContractWalletAddress: string;
+  inboxId: string;
+}): Promise<CreateUserResponse> => {
+  const { privyUserId, smartContractWalletAddress, inboxId } = args;
+
+  const requestData = {
+    privyUserId,
+    device: {
+      os: Platform.OS.toLowerCase(),
+      name: Device.modelId,
+    },
+    identity: {
+      privyAddress: smartContractWalletAddress,
+      xmtpId: inboxId,
+    },
+  };
+
+  const response = await api.post<CreateUserResponse>(
+    "/api/v1/users",
+    requestData
+  );
+  return createUserResponseSchema.parse(response.data);
+};
+
+const fetchJwtResponseSchema = z.object({
+  jwt: z.string(),
+});
+
+type FetchJwtResponse = z.infer<typeof fetchJwtResponseSchema>;
+
+export async function fetchJwt() {
+  // todo(lustig) look at the endpoint this actually is
+  // const response = await api.post<FetchJwtResponse>("/api/v1/authenticate");
+  // return fetchJwtResponseSchema.parse(response.data);
+  // https://xmtp-labs.slack.com/archives/C07NSHXK693/p1739877738959529
+  const dummyJwtUntilJwtBackendWorks = "dummyJwtUntilJwtBackendWorks";
+  return dummyJwtUntilJwtBackendWorks;
+}

utils/api/auth.ts features/authentication/authentication.headers.ts

@@ -1,11 +1,13 @@
-import { tryGetAppCheckToken } from "../appCheck";
+import { tryGetAppCheckToken } from "../../utils/appCheck";
 import { MultiInboxClient } from "@/features/multi-inbox/multi-inbox.client";
 import {
   getSafeCurrentSender,
   useAccountsStore,
 } from "@/features/multi-inbox/multi-inbox.store";
 import { MultiInboxClientRestorationStates } from "@/features/multi-inbox/multi-inbox-client.types";
 import { toHex } from "viem";
+import { ensureJwtQueryData } from "./jwt.query";
+import { AuthenticationError } from "@/utils/error";
 
 export const XMTP_INSTALLATION_ID_HEADER_KEY = "X-XMTP-InstallationId";
 export const XMTP_INBOX_ID_HEADER_KEY = "X-XMTP-InboxId";
@@ -22,7 +24,16 @@ export type XmtpApiHeaders = {
   [XMTP_SIGNATURE_HEADER_KEY]: string;
 };
 
-export async function getConvosApiHeaders(): Promise<XmtpApiHeaders> {
+/**
+ * Returns the headers required to authenticate with the XMTP API.
+ * As of February 18, 2025, these headers are only required for two endpoints:
+ * 1. Create User endpoint - Creates a new user account
+ * 2. Authenticate endpoint - Creates a new JWT for an existing user
+ *
+ * Note: We don't use refresh tokens since users are already authenticated via
+ * Privy passkeys. See authentication.readme.md for more details.
+ */
+export async function getConvosAuthenticationHeaders(): Promise<XmtpApiHeaders> {
   const currentEthereumAddress = getSafeCurrentSender().ethereumAddress;
   const areInboxesRestored =
     useAccountsStore.getState().multiInboxClientRestorationState ===
@@ -33,19 +44,21 @@ export async function getConvosApiHeaders(): Promise<XmtpApiHeaders> {
   });
 
   if (!appCheckToken) {
-    throw new Error(
+    throw new AuthenticationError(
       "No App Check Token Available. This indicates that we believe the app is not running on an authentic build of our application on a device that has not been tampered with."
     );
   }
 
   if (!areInboxesRestored) {
-    throw new Error(
-      "[getConvosApiHeaders] Inboxes not restored; cannot create headers"
+    throw new AuthenticationError(
+      "[getConvosAuthenticationHeaders] Inboxes not restored; cannot create headers"
     );
   }
 
   if (!inboxClient) {
-    throw new Error("[getConvosApiHeaders] No inbox client found for account");
+    throw new AuthenticationError(
+      "[getConvosAuthenticationHeaders] No inbox client found for account"
+    );
   }
 
   const rawAppCheckTokenSignature = await inboxClient.signWithInstallationKey(
@@ -60,3 +73,19 @@ export async function getConvosApiHeaders(): Promise<XmtpApiHeaders> {
     [XMTP_SIGNATURE_HEADER_KEY]: appCheckTokenSignatureHexString,
   };
 }
+
+/**
+ * Returns the headers required to authenticate with the API.
+ * As of February 18, 2025, these headers are only required for two endpoints:
+ * 1. Create User endpoint - Creates a new user account
+ * 2. Authenticate endpoint - Creates a new JWT for an existing user
+ *
+ * Note: We don't use refresh tokens since users are already authenticated via
+ * Privy passkeys. See authentication.readme.md for more details.
+ */
+export async function getConvosAuthenticatedHeaders() {
+  const jwt = await ensureJwtQueryData();
+  return {
+    Authorization: `Bearer ${jwt}`,
+  };
+}

features/authentication/authentication.readme.md

@@ -0,0 +1,89 @@
+# Authentication Module
+
+This document provides a high-level overview of the authentication strategy used in our application, explaining the flow involving Firebase AppCheck, XMTP, and Ethereum wallet integration via Privy passkeys, as well as the two primary endpoints for user creation and authentication.
+
+## Loom Recordings
+
+[Convos Authentication Modeling Discussion](https://www.loom.com/share/0a1277074f2a4e989ecfe0141deac359)  
+Participants: Ry, Michael, Thierry  
+Date: Friday February 14, 2025
+
+## Overview
+
+Our authentication mechanism involves two primary endpoints:
+
+- **Create User Endpoint**: Creates a new user account. It accepts four header keys and optional profile data.
+- **Authenticate Endpoint**: Authenticates an existing user and returns a JSON Web Token (JWT) for subsequent requests.
+
+All other endpoints require the JWT for authentication.
+
+## Authentication Flow
+
+1. **Passkey Authentication via Privy**
+
+   - The user logs in using a passkey with Privy
+   - Successful authentication provides access to a Privy account, which in turn gives access to a smart contract Ethereum wallet
+
+2. **Smart Contract Wallet as Signer**
+
+   - The Ethereum wallet obtained from Privy acts as the cryptographic signer
+   - This wallet is used to create an XMTP inbox
+
+3. **Signing the Firebase AppCheck Token**
+
+   - The Firebase AppCheck token is provided by Firebase
+   - The XMTP inbox on the client side signs the AppCheck token
+   - The backend then verifies the cryptographic signature
+
+4. **JWT Generation**
+   - Once verified, the backend issues a JWT
+   - This JWT is then used to authenticate all subsequent API requests
+   - There is no refresh token as the persistent cryptographic signer (passkey via Privy) handles re-authentication
+
+## Endpoints
+
+### Create User Endpoint
+
+**Purpose**: Creates a new user account
+
+**Headers** (all four required):
+
+1. **Installation ID**: Identifier for the XMTP inbox, derived from the device
+2. **Firebase AppCheck Token**: Provided by Firebase
+3. **Signed AppCheck Token**: The Firebase AppCheck token signed by the XMTP inbox (client-side)
+4. **XMTP Inbox ID**: The XMTP inbox ID of the user, created during the onboarding flow
+
+**Profile Data** (optional but currently always provided):
+
+- `profile_name`: Must be between 3 and 30 characters
+- `avatar_url`: No strict URL validation is enforced at this time
+- `description`: Cannot exceed 500 characters
+
+**Response**: Returns the newly created user's ID along with metadata such as createdAt, updatedAt, and the provided profile information
+
+### Authenticate Endpoint
+
+**Purpose**: Authenticates an existing user
+
+**Headers** (same four as above):
+
+- Installation ID
+- Firebase AppCheck Token
+- Signed AppCheck Token
+- Ethereum Wallet
+
+**Response**: Returns a JWT which is used for authenticating all further API calls
+
+## Package Organization
+
+All authentication-related code and documentation are located in the `feature/authentication` directory.
+
+## Additional Notes
+
+### Security
+
+The Firebase AppCheck token is signed on the client side by the XMTP inbox and verified by the backend. The integration with Privy and the smart contract wallet removes the need for refresh tokens, as the persistent signer can always re-authenticate.
+
+### Profile Data Validation
+
+Currently, the profile creation is always provided during the Create User process. In future iterations, if profile creation becomes optional or additional validation (e.g., URL validation for avatars) is required, this documentation and the corresponding code should be updated accordingly.

features/authentication/interceptor.headers.ts

@@ -0,0 +1,45 @@
+import { AxiosRequestConfig } from "axios";
+import {
+  getConvosAuthenticationHeaders,
+  getConvosAuthenticatedHeaders,
+} from "@/features/authentication/authentication.headers";
+import { AuthenticationError } from "../../utils/error";
+
+/**
+ * These routes are special because they need to be called before we have a JWT.
+ * They receive headers that cryptographically prove the user owns the inboxes
+ * and wallet they claim to own.
+ *
+ * The headers include:
+ * - App Check token to verify authentic app build
+ * - XMTP Installation ID to verify XMTP client
+ * - XMTP Inbox ID to identify the user's inbox
+ * - XMTP Signature of the app check token to prove ownership of the inbox
+ *
+ * See authentication.readme.md for more details on the authentication flow
+ * and how these headers are used to establish trust before issuing a JWT.
+ */
+const AuthenticationRoutes = ["/api/v1/users", "/api/v1/authenticate"] as const;
+
+export const headersInterceptor = async (config: AxiosRequestConfig) => {
+  const url = config.url;
+
+  if (!url) {
+    throw new AuthenticationError("No URL provided in request config");
+  }
+
+  const needsAuthenticationHeaders = AuthenticationRoutes.some((route) =>
+    url.includes(route)
+  );
+
+  const headers = needsAuthenticationHeaders
+    ? await getConvosAuthenticationHeaders()
+    : await getConvosAuthenticatedHeaders();
+
+  config.headers = {
+    ...config.headers,
+    ...headers,
+  };
+
+  return config;
+};