Better Auth – Sign In With Farcaster (SIWF)

Authenticate users via Farcaster using Better Auth. This plugin mirrors the developer experience of the official SIWE plugin while adapting flows and schema to Farcaster identities.

• Server plugin: siwf
• Client plugin: siwfClient
• REST endpoints: POST /siwf/verify

References: see the official SIWE plugin docs for structure and expectations and an earlier community attempt for Farcaster-specific ideas: SIWE Plugin Docs, it's also an expansion of this other plugin Farcaster Auth Plugin.

Installation

npm i better-auth-siwf

Server Setup

Add the SIWF plugin to your Better Auth configuration.

// auth.ts
import { betterAuth } from "better-auth";
import { type ResolveFarcasterUserResult, siwf } from "better-auth-siwf";

const auth = betterAuth({
	// ... your better-auth config
	plugins: [
		siwf({
			hostname: "app.example.com",
			allowUserToLink: false,
			// Optional: resolve the user data from neynar for example
			// see neynar docs: https://docs.neynar.com/reference/fetch-bulk-users
			resolveFarcasterUser: async ({
				fid,
			}): Promise<ResolveFarcasterUserResult | null> => {
				const data = await fetch(
					`https://api.neynar.com/v2/farcaster/user/bulk/?fids=${fid}`,
					{
						method: "GET",
						headers: {
							"x-api-key": process.env.NEYNAR_API_KEY,
							"Content-Type": "application/json",
						},
					},
				).then(async (data) => await data.json());

				if (!data || data.users.length === 0) {
					return null;
				}

				const user = data.users[0];
				return {
					fid,
					username: user.username,
					displayName: user.display_name,
					avatarUrl: user.pfp_url,
					custodyAddress: user.custody_address,
					verifiedAddresses: {
						primary: {
							ethAddress:
								user.verified_addresses.primary.eth_address ?? undefined,
							solAddress:
								user.verified_addresses.primary.sol_address ?? undefined,
						},
						ethAddresses: user.verified_addresses?.eth_addresses ?? undefined,
						solAddresses: user.verified_addresses?.sol_addresses ?? undefined,
					},
				} satisfies ResolveFarcasterUserResult;
			},
		}),
	],
});

What the plugin does

• Exposes POST /siwf/signin to signin a Farcaster Quick Auth JWT and establish a Better Auth session cookie.
• Creates a user if one does not exist, associates it with a farcaster record.
• Sets a secure session cookie with SameSite: "none" for Farcaster MiniApp compatibility.

Client Setup

Add the client plugin so the Better Auth client exposes SIWF endpoints.

// auth-client.ts
import { createAuthClient } from "better-auth/react";
import { siwfClient, type SIWFClientType } from "better-auth-siwf";

const client = createAuthClient({
  plugins: [siwfClient()],
  fetchOptions: {
    credentials: "include", // Required for session cookies
  },
});

// Type the client to include custom farcaster methods
export const authClient = client as typeof client & SIWFClientType;

Usage

1) Obtain a Farcaster JWT token on the client

Use Farcaster Quick Auth (within a Farcaster MiniApp) to obtain a signed JWT for your domain. Ensure the domain used here matches the server plugin domain.

const result = await miniappSdk.quickAuth.getToken(); // result: { token: string }

2) Verify and sign in

Send the token and user details to the Better Auth server. On success, the Better Auth session cookie is set.

const ctx = await miniappSdk.context;
const { data } = await authClient.signInWithFarcaster({
  token: result.token,
  user: {
    ...ctx.user
    notificationDetails: ctx.client.notificationDetails
      ? [
          {
            ...ctx.client.notificationDetails,
            appFid: (await miniappSdk.context).client.clientFid
          }
        ]
      : [],
  }
});

// data.success === true
// data.user -> { id, fid, name, image }

All together:

import { sdk as miniappSdk } from "@farcaster/miniapp-sdk";
import { authClient } from "@/lib/auth-client";

const farcasterSignIn = async () => {
  const isInMiniapp = await miniappSdk.isInMiniApp();
  if (!isInMiniapp) {
    return;
  }

  const ctx = await miniappSdk.context;
  
  // 1. Obtain a Farcaster JWT token on the client
  const result = await miniappSdk.quickAuth.getToken();
  if (!result || !result.token) {
    throw new Error("Failed to get token");
  }

  // 2. Verify and sign in with the Better Auth server
  const { data } = await authClient.siwf.verifyToken({
    token: result.token,
    user: {
      ...ctx.user
      notificationDetails: ctx.client.notificationDetails
        ? [
            {
              ...ctx.client.notificationDetails,
              appFid: (await miniappSdk.context).client.clientFid
            }
          ]
        : [],
    }
  });
  if (!data.success) {
    throw new Error("Failed to verify token");
  }
  console.log("Signed in", data.user);
};

Configuration Options

Server options accepted by siwf:

• domain (string, required): Domain expected in the Farcaster JWT. Must match exactly.
• schema (optional): Extend or override the default plugin schema via Better Auth mergeSchema.
• resolveFarcasterUser (function): Resolve a Farcaster user via farcaster hubs.

Client plugin siwfClient has no options; it exposes the plugin namespace in the Better Auth client.

Database Schema

This plugin merges the following tables into your Better Auth schema.

farcaster

| Field | Type | Notes | |----------------------|---------|------------------------------------| | userId | string | References user.id (required) | | fid | number | Unique Farcaster ID (required) | | username | string | Optional | | displayName | string | Optional | | avatarUrl | string | Optional | | notificationDetails | json | Optional (MiniApp notification array) | | createdAt | date | Required | | updatedAt | date | Required |

walletAddress

| Field | Type | Notes | |----------------------|---------|------------------------------------| | userId | string | References user.id (required) | | address | string | The wallet address (required) | | chainId | number | The chain ID (required) | | isPrimary | boolean | Whether the address is primary (required) | | createdAt | date | Required |

Migrations

Use the Better Auth CLI to migrate or generate schema:

npx @better-auth/cli migrate
# or
npx @better-auth/cli generate

Alternatively, add the fields manually based on the tables above.

Security Notes

• The server verifies Farcaster JWTs with the configured domain. Mismatched domains will fail.
• Session cookies are set with secure: true, httpOnly: true, and sameSite: "none" for MiniApp compatibility. Serve over HTTPS.
• The plugin @farcaster/quick-auth ensures the JWT sub (subject) matches the provided fid before issuing a session.

Troubleshooting

• 401 "Invalid Farcaster user": The JWT subject must equal the provided fid.
• No session cookie set: In embedded contexts (MiniApps), ensure third-party cookies are allowed and your server uses HTTPS with SameSite: none.
• Domain mismatch: The JWT must be issued for the same domain configured in the plugin.

Acknowledgements

• Structure and schema patterns inspired by the official Better Auth SIWE plugin: SIWE Plugin Docs
• Community exploration for Farcaster auth flows: Community Farcaster Auth Plugin