[SDK]: add backend wallets for in app wallet (#5878)

---
title: "[SDK] Feature: add backend wallets for  in app wallet"
---

https://linear.app/thirdweb/issue/TOOL-2884/backend-server-wallets

## Notes for the reviewer
This also fixes the cache mechanics for thirdweb clients to include a partial string of the secret key. Was running into an issue where the client was originall instantiated without the secret key and even when a new client with secret key was passed in, we keep falling back to the cached client without secret key

## How to test
Add a button on playground with a client that has secret key and create a new backend wallet.

<!-- start pr-codex -->

---

## PR-Codex overview
This PR introduces support for backend wallets in the `thirdweb` library, allowing applications to authenticate users with a backend strategy, enhancing security by managing wallet access without exposing private keys.

### Detailed summary
- Added `backend` strategy for wallet authentication.
- Updated `authenticate` function to support `backend` strategy.
- Introduced `backendAuthenticate` function for backend authentication.
- Updated `InAppWebConnector` and `InAppNativeConnector` to handle `backend` strategy.
- Modified type definitions to include `backend` strategy.
- Added tests for `backendAuthenticate` and its integration in connectors.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->

Author: ElasticBottle

.changeset/popular-ravens-reflect.md

@@ -0,0 +1,23 @@
+---
+"thirdweb": minor
+---
+
+Add support for backend wallets.
+
+This is useful is you have a backend that is connected to an that you want to have programmatic access to a wallet without managing private keys.
+
+Here's how you'd do it:
+
+```typescript
+const wallet = inAppWallet();
+const account = await wallet.connect({
+    strategy: "backend",
+    client: createThirdwebClient({
+        secretKey: "...",
+    }),
+    walletSecret: "...",
+  });
+console.log("account.address", account.address);
+```
+
+Note that `walletSecret` should be generated by you and securely stored to uniquely authenticate to the given wallet.

packages/thirdweb/src/wallets/in-app/core/authentication/backend.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from "vitest";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import { getClientFetch } from "../../../../utils/fetch.js";
+import { stringify } from "../../../../utils/json.js";
+import { backendAuthenticate } from "./backend.js";
+import { getLoginUrl } from "./getLoginPath.js";
+
+// Mock dependencies
+vi.mock("../../../../utils/fetch.js");
+vi.mock("./getLoginPath.js");
+
+describe("backendAuthenticate", () => {
+  it("should successfully authenticate and return token", async () => {
+    // Mock response data
+    const mockResponse = {
+      token: "mock-token",
+      cookieString: "mock-cookie",
+    };
+
+    // Mock fetch implementation
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockResponse),
+    });
+
+    // Mock dependencies
+    vi.mocked(getClientFetch).mockReturnValue(mockFetch);
+    vi.mocked(getLoginUrl).mockReturnValue("/auth/login");
+
+    const result = await backendAuthenticate({
+      client: TEST_CLIENT,
+      walletSecret: "test-secret",
+    });
+
+    // Verify the fetch call
+    expect(mockFetch).toHaveBeenCalledWith("/auth/login", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: stringify({ walletSecret: "test-secret" }),
+    });
+
+    // Verify response
+    expect(result).toEqual(mockResponse);
+  });
+
+  it("should throw error when authentication fails", async () => {
+    // Mock failed fetch response
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+    });
+
+    // Mock dependencies
+    vi.mocked(getClientFetch).mockReturnValue(mockFetch);
+    vi.mocked(getLoginUrl).mockReturnValue("/auth/login");
+
+    // Test inputs
+    const args = {
+      client: TEST_CLIENT,
+      walletSecret: "test-secret",
+    };
+
+    // Verify error is thrown
+    await expect(backendAuthenticate(args)).rejects.toThrow(
+      "Failed to generate backend account",
+    );
+  });
+});

packages/thirdweb/src/wallets/in-app/core/authentication/backend.ts

@@ -0,0 +1,36 @@
+import type { ThirdwebClient } from "../../../../client/client.js";
+import { getClientFetch } from "../../../../utils/fetch.js";
+import { stringify } from "../../../../utils/json.js";
+import type { Ecosystem } from "../wallet/types.js";
+import { getLoginUrl } from "./getLoginPath.js";
+import type { AuthStoredTokenWithCookieReturnType } from "./types.js";
+
+/**
+ * Authenticates via the wallet secret
+ * @internal
+ */
+export async function backendAuthenticate(args: {
+  client: ThirdwebClient;
+  walletSecret: string;
+  ecosystem?: Ecosystem;
+}): Promise<AuthStoredTokenWithCookieReturnType> {
+  const clientFetch = getClientFetch(args.client, args.ecosystem);
+  const path = getLoginUrl({
+    authOption: "backend",
+    client: args.client,
+    ecosystem: args.ecosystem,
+  });
+  const res = await clientFetch(`${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: stringify({
+      walletSecret: args.walletSecret,
+    }),
+  });
+
+  if (!res.ok) throw new Error("Failed to generate backend account");
+
+  return (await res.json()) satisfies AuthStoredTokenWithCookieReturnType;
+}

packages/thirdweb/src/wallets/in-app/core/authentication/types.ts

@@ -74,7 +74,10 @@ export type SingleStepAuthArgsType =
     }
   | {
       strategy: "guest";
-      client: ThirdwebClient;
+    }
+  | {
+      strategy: "backend";
+      walletSecret: string;
     };
 
 export type AuthArgsType = (MultiStepAuthArgsType | SingleStepAuthArgsType) & {
@@ -89,6 +92,7 @@ type RecoveryShareManagement = "USER_MANAGED" | "AWS_MANAGED" | "ENCLAVE";
 export type AuthProvider =
   | "Cognito"
   | "Guest"
+  | "Backend"
   | "Google"
   | "EmailOtp"
   | "CustomJWT"

packages/thirdweb/src/wallets/in-app/core/wallet/in-app-core.ts

@@ -26,7 +26,11 @@ export async function getOrCreateInAppWalletConnector(
   connectorFactory: (client: ThirdwebClient) => Promise<InAppConnector>,
   ecosystem?: Ecosystem,
 ) {
-  const key = stringify({ clientId: client.clientId, ecosystem });
+  const key = stringify({
+    clientId: client.clientId,
+    ecosystem,
+    partialSecretKey: client.secretKey?.slice(0, 5),
+  });
   if (connectorCache.has(key)) {
     return connectorCache.get(key) as InAppConnector;
   }

packages/thirdweb/src/wallets/in-app/native/auth/index.ts

@@ -133,6 +133,17 @@ export async function preAuthenticate(args: PreAuthArgsType) {
  *  verificationCode: "123456",
  * });
  * ```
+ *
+ * Authenticate to a backend account (only do this on your backend):
+ * ```ts
+ * import { authenticate } from "thirdweb/wallets/in-app";
+ *
+ * const result = await authenticate({
+ *  client,
+ *  strategy: "backend",
+ *  walletSecret: "...", // Provided by your app
+ * });
+ * ```
  * @wallet
  */
 export async function authenticate(args: AuthArgsType) {

packages/thirdweb/src/wallets/in-app/native/native-connector.ts

@@ -4,6 +4,7 @@ import { nativeLocalStorage } from "../../../utils/storage/nativeStorage.js";
 import type { Account } from "../../interfaces/wallet.js";
 import { getUserStatus } from "../core/actions/get-enclave-user-status.js";
 import { authEndpoint } from "../core/authentication/authEndpoint.js";
+import { backendAuthenticate } from "../core/authentication/backend.js";
 import { ClientScopedStorage } from "../core/authentication/client-scoped-storage.js";
 import { guestAuthenticate } from "../core/authentication/guest.js";
 import { customJwt } from "../core/authentication/jwt.js";
@@ -171,6 +172,13 @@ export class InAppNativeConnector implements InAppConnector {
           storage: nativeLocalStorage,
         });
       }
+      case "backend": {
+        return backendAuthenticate({
+          client: this.client,
+          walletSecret: params.walletSecret,
+          ecosystem: params.ecosystem,
+        });
+      }
       case "wallet": {
         return siweAuthenticate({
           client: this.client,
@@ -179,6 +187,11 @@ export class InAppNativeConnector implements InAppConnector {
           ecosystem: params.ecosystem,
         });
       }
+      case "github":
+      case "twitch":
+      case "steam":
+      case "farcaster":
+      case "telegram":
       case "google":
       case "facebook":
       case "discord":

packages/thirdweb/src/wallets/in-app/web/in-app.ts

@@ -139,6 +139,20 @@ import { createInAppWallet } from "../core/wallet/in-app-core.js";
  * });
  * ```
  *
+ * ### Connect to a backend account
+ *
+ * ```ts
+ * import { inAppWallet } from "thirdweb/wallets";
+ *
+ * const wallet = inAppWallet();
+ *
+ * const account = await wallet.connect({
+ *   client,
+ *   strategy: "backend",
+ *   walletSecret: "...", // Provided by your app
+ * });
+ * ```
+ *
  * ### Connect with custom JWT (any OIDC provider)
  *
  * You can use any OIDC provider to authenticate your users. Make sure to configure it in your dashboard under in-app wallet settings.

packages/thirdweb/src/wallets/in-app/web/lib/auth/index.ts

@@ -140,6 +140,17 @@ export async function preAuthenticate(args: PreAuthArgsType) {
  *  verificationCode: "123456",
  * });
  * ```
+ *
+ * Authenticate to a backend account (only do this on your backend):
+ * ```ts
+ * import { authenticate } from "thirdweb/wallets/in-app";
+ *
+ * const result = await authenticate({
+ *  client,
+ *  strategy: "backend",
+ *  walletSecret: "...", // Provided by your app
+ * });
+ * ```
  * @wallet
  */
 export async function authenticate(args: AuthArgsType) {