@daimo/auth-client
v0.1.0
Published
A framework agnostic client library for Farcaster Auth.
Downloads
236
Keywords
Readme
@farcaster/auth-client
A framework agnostic client library for Farcaster Auth.
Getting Started
Installation
Install the library and its peer dependency viem.
npm install @farcaster/auth-client viem
Clients
If you're building a connected app, use an app client. An app client can connect to the relay server, generate a Sign in With Farcaster link, and verify the user's signature.
If you're building a wallet app and receiving signature requests, use a wallet client. A wallet client can parse a Sign in With Farcaster URL, build a message to present to the user, and submit the signed message to the relay server.
App Client
You can use an app client to create a Farcaster Auth relay channel, generate a URL to request a signature from the user's Farcaster wallet app, and verify the returned signature.
import { createAppClient, viemConnector } from "@farcaster/auth-client";
const appClient = createAppClient({
relay: "https://relay.farcaster.xyz",
ethereum: viemConnector(),
});
Parameters
ethereum
An Ethereum connector, used to query the Farcaster contracts and verify smart contract wallet signatures. @farcaster/auth-client
currently provides only the viemConnector
connector type.
To use a custom RPC, pass an RPC URL to the viem connector.
Type: Ethereum
Example: viemConnector("http://mainnet.optimism.io")
relay (optional)
Relay server URL. Defaults to the public relay at https://relay.farcaster.xyz
.
Type: string
Example: "https://relay.farcaster.xyz"
version (optional)
Farcaster Auth version. Defaults to "v1"
Type: string
Example: "v1"
Actions
createChannel
Create a Farcaster Auth relay channel.
Returns a secret token identifying the channel, and a URI to display to the end user as a link or QR code.
const channel = await appClient.createChannel({
siweUri: "https://example.com/login",
domain: "example.com",
});
Return Value
{
response: Response;
data: {
channelToken: string;
url: string;
}
isError: boolean;
error: Error;
}
Parameters
siweUri
Login URL for your application.
Type: string
Example: "https://example.com/login"
domain
Domain of your application. Value should match the domain requesting the SIWE signature.
Type: string
Example: "example.com"
nonce (optional)
A custom nonce. Must be at least 8 alphanumeric characters.
Type: string
Example: "ESsxs6MaFio7OvqWb"
notBefore (optional)
Start time at which the SIWE signature becomes valid. ISO 8601 datetime.
Type: string
Example: "2023-12-20T23:21:24.917Z"
expirationTime (optional)
Expiration time at which the SIWE signature is no longer valid. ISO 8601 datetime.
Type: string
Example: "2023-12-20T23:21:24.917Z"
requestId (optional)
A system specific ID your app can use to refer to the sign in request.
Type: string
Example: "8d0494d9-e0cf-402b-ab0a-394ac7fe07a0"
status
Get current status of a Farcaster Auth request.
Returns the current state of the request, either 'pending'
if the user's Farcaster wallet app has not yet sent back a signature, or 'completed'
once the wallet app has returned a response.
In 'completed'
state, the response includes the generated Sign in With Farcaster message, a signature from the user's custody address, the user's verified fid, and user profile information.
const status = await appClient.status({
channelToken: "210f1718-427e-46a4-99e3-2207f21f83ec",
});
Return Value
{
response: Response
data: {
state: 'pending' | 'completed'
nonce: string
message?: string
signature?: Hex
fid?: number
username?: string
bio?: string
displayName?: string
pfpUrl?: string
custody?: Hex
verifications?: Hex[]
}
isError: boolean
error: Error
}
Parameters
channelToken
Farcaster Auth relay channel token, returned by createChannel
.
Type: string
Example: "210f1718-427e-46a4-99e3-2207f21f83ec"
watchStatus
Poll for the current status of a Farcaster Auth request.
When the status changes to 'complete'
this action resolves with the final channel value, including the Sign In With Farcaster message, signature, and user profile information.
const status = await appClient.watchStatus({
channelToken: "210f1718-427e-46a4-99e3-2207f21f83ec",
timeout: 60_000,
interval: 1_000,
onResponse: ({ response, data }) => {
console.log("Response code:", response.status);
console.log("Status data:", data);
},
});
Return Value
{
response: Response
data: {
state: 'completed'
nonce: string
message?: string
signature?: Hex
fid?: number
username?: string
bio?: string
displayName?: string
pfpUrl?: string
custody?: Hex
verifications?: Hex[]
}
isError: boolean
error: Error
}
Parameters
channelToken
Farcaster Auth relay channel token, returned by createChannel
.
Type: string
Example: "210f1718-427e-46a4-99e3-2207f21f83ec"
timeout (optional)
Polling timeout, in milliseconds. If the auth request is not completed before the timeout, watchStatus
returns an error.
Type: number
Example: 300_000
interval (optional)
Polling interval, in milliseconds. The client will check for updates at this frequency.
Type: number
Example: 1_000
onResponse (optional)
Callback function invoked each time the client polls for an update and receives a response from the relay server. Receives the return value of the latest status
request.
Type: ({ response, data }) => void
Example:
({ response, data }) => {
console.log("Response code:", response.status);
console.log("Status data:", data);
};
verifySignInMessage
Verify a Sign In With Farcaster message. Your app should call this function and check that it succeeds after reading the message and signature provided by the user's Farcaster wallet over the Auth relay channel.
Returns the parsed Sign in With Farcaster message, the user's fid, and whether the verification succeeded.
const { data, success, fid } = await appClient.verifySignInMessage({
nonce: "abcd1234",
domain: "example.com",
message: "example.com wants you to sign in with your Ethereum account: [...]",
signature: "0x9335c3055d47780411a3fdabad293c68c84ea350a11794cdc811fd51b[...]",
});
Return Value
{
data: SiweMessage,
success: boolean,
fid: number
isError: boolean
error: Error
}
Parameters
nonce
The nonce generated by your application. Must match the nonce in the SIWE message.
Type: string
Example: "ESsxs6MaFio7OvqWb"
domain
Domain of your application. Value must match the domain in the SIWE message.
Type: string
Example: "example.com"
message
The Sign in With Farcaster message to verify. This may be either a string or a parsed SiweMessage
. Your app should read this value from the Auth relay channel once the request is completed.
Type: string | SiweMessage
Example: "example.com wants you to sign in with your Ethereum account: [...]"
signature
Signature provided by the user's Farcaster wallet. Your app should read this from the Auth relay channel once the request is completed.
Type: 0x${string}
Example: "0x9335c3055d4778013fdabad293c68c84ea350a11794cdc121c71fd51b[...]"
Auth Client
If you're building a wallet app and receiving signature requests, use a wallet client.
You can use an wallet client to parse an incoming Sign In With Farcaster request URL, build a Sign In With Farcaster message to present to the user, and submit the signed message to a Farcaster Auth relay channel.
import { createWalletClient, viemConnector } from "@farcaster/auth-client";
const walletClient = createWalletClient({
relay: "https://relay.farcaster.xyz",
ethereum: viemConnector(),
});
Parameters
ethereum
An Ethereum connector, used to query the Farcaster contracts and verify smart contract wallet signatures. @farcaster/auth-client
currently provides only the viem
connector type.
To use a custom RPC, pass an RPC URl to the viem connector.
Type: Ethereum
Example: viem("http://mainnet.optimism.io")
relay (optional)
Relay server URL. Defaults to the public relay at https://relay.farcaster.xyz
.
Type: string
Example: "https://relay.farcaster.xyz"
version (optional)
Farcaster Auth version. Defaults to "v1"
Type: string
Example: "v1"
Actions
parseSignInURI
Parse the Sign In With Farcaster URI provided by a connected app user.
Returns the parsed parameters. Your app should use these to construct a Sign In With Farcaster message.
Returns an error if URI is invalid.
const params = walletClient.parseSignInURI({
uri: "farcaster://connect?channelToken=76be6229-bdf7-4ad2-930a-540fb2de1e08&nonce=ESsxs6MaFio7OvqWb&siweUri=https%3A%2F%2Fexample.com%2Flogin&domain=example.com",
});
Return Value
{
channelToken: string
params: {
domain: string
uri: string
nonce: string
notBefore?: string
expirationTime?: string
requestId?: string
}
isError: boolean
error: Error
}
Parameters
uri
Sign In With Farcaster protocol handler URI.
Type: string
Example: "farcaster://connect?channelToken=76be6229-bdf7-4ad2-930a-540fb2de1e08&nonce=ESsxs6MaFio7OvqWb&siweUri=https%3A%2F%2Fexample.com%2Flogin&domain=example.com"
buildSignInMessage
Build a Sign In With Farcaster message to present to the end user.
Adds required Sign In With Farcaster message attributes to any provided parameters. You should parse most of these parameters from the provided protocol URI. Your wallet app must provide the user's custody address and fid.
Returns a SiweMessage
object and the message as a string.
const { siweMessage, message } = walletClient.buildSignInMessage({
address: "0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231",
fid: 1,
uri: "https://example.com/login",
domain: "example.com",
nonce: "ESsxs6MaFio7OvqWb",
});
Return Value
{
siweMessage: SiweMessage;
message: string;
isError: boolean;
error: Error;
}
Parameters
address
Wallet user's custody address. This address must sign the generated Sign In With Farcaster message. Your wallet app should provide the custody address of the authenticated user.
Type: 0x${string}
Example: "0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231"
fid
Wallet user's fid. Your wallet app should provide the fid of the authenticated user.
Type: number
Example: 1
uri
Login URL of the relying connected app. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "https://example.com/login"
domain
Domain of the relying connected app. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "example.com"
nonce
Random nonce to include in the Sign In With Farcaster message. Must be at least 8 alphanumeric characters. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "ESsxs6MaFio7OvqWb"
notBefore (optional)
Start time at which the SIWE signature becomes valid. ISO 8601 datetime. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "2023-12-20T23:21:24.917Z"
expirationTime (optional)
Expiration time at which the SIWE signature is no longer valid. ISO 8601 datetime. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "2023-12-20T23:21:24.917Z"
requestId (optional)
A system specific ID provided by the relying app. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "8d0494d9-e0cf-402b-ab0a-394ac7fe07a0"
authenticate
Submit a Sign In With Farcaster message, user signature, and profile data to the Auth relay server.
const params = walletClient.authenticate({
message: "example.com wants you to sign in with your Ethereum account: [...]",
signature: "0x9335c3055d47780411a3fdabad293c68c84ea350a11794cdc811fd51b[...]",
fid: 1,
username: "alice",
bio: "I'm a little teapot who didn't fill out my bio",
displayName: "Alice Teapot",
pfpUrl: "https://images.example.com/profile.png",
});
Return Value
{
response: Response
data: {
state: 'completed'
nonce: string
message?: string
signature?: `0x${string}`
fid?: number
username?: string
bio?: string
displayName?: string
pfpUrl?: string
}
isError: boolean
error: Error
}
Parameters
message
The Sign in With Farcaster message produced by your wallet app and signed by the user.
Type: string
Example: "example.com wants you to sign in with your Ethereum account: [...]"
signature
SIWE signature created by the wallet user's account.
Type: 0x${string}
Example: "0x9335c3055d4778013fdabad293c68c84ea350a11794cdc121c71fd51b[...]"
fid
Wallet user's fid.
Type: number
Example: 1
username
Wallet user's Farcaster username.
Type: string
Example: "alice"
bio
Wallet user's bio.
Type: string
Example: "I'm a little teapot who didn't fill out my bio"
displayName
Wallet user's display name.
Type: string
Example: "Alice Teapot"
pfpUrl
Wallet user's profile photo URL.
Type: string
Example: "https://images.example.com/profile.png"