feat(firefly): add firefly session bind and restore with farcaster integration

Author: swkatmask

cspell.json

@@ -269,6 +269,7 @@
         "linkedin",
         "luma",
         "muln",
+        "pathnames",
         "reposted",
         "reposts",
         "sepolia",
@@ -278,6 +279,7 @@
         "txid",
         "waitlist",
         "WARPCAST",
+        "webm",
         "youtube"
     ]
 }

packages/mask/popups/pages/Personas/ConnectFirefly/bindFireflySession.ts

@@ -0,0 +1,65 @@
+import {
+    FarcasterSession,
+    FIREFLY_ROOT_URL,
+    fireflySessionHolder,
+    patchFarcasterSessionRequired,
+    resolveFireflyResponseData,
+} from '@masknet/web3-providers'
+import { SessionType, type FireflyConfigAPI, type Session } from '@masknet/web3-providers/types'
+import urlcat from 'urlcat'
+
+async function bindFarcasterSessionToFirefly(session: FarcasterSession, signal?: AbortSignal) {
+    const isGrantByPermission = FarcasterSession.isGrantByPermission(session, true)
+    const isRelayService = FarcasterSession.isRelayService(session)
+
+    if (!isGrantByPermission && !isRelayService)
+        throw new Error(
+            '[bindFarcasterSessionToFirefly] Only grant-by-permission or relay service sessions are allowed.',
+        )
+
+    const response = await fireflySessionHolder.fetch<FireflyConfigAPI.BindResponse>(
+        urlcat(FIREFLY_ROOT_URL, '/v3/user/bindFarcaster'),
+        {
+            method: 'POST',
+            body: JSON.stringify({
+                token: isGrantByPermission ? session.signerRequestToken : undefined,
+                channelToken: isRelayService ? session.channelToken : undefined,
+                isForce: false,
+            }),
+            signal,
+        },
+    )
+
+    if (response.error?.some((x) => x.includes('Farcaster binding timed out'))) {
+        throw new Error('Bind Farcaster account to Firefly timeout.')
+    }
+
+    // If the farcaster is already bound to another account, throw an error.
+    if (
+        isRelayService &&
+        response.error?.some((x) => x.includes('This farcaster already bound to the other account'))
+    ) {
+        throw new Error('This Farcaster account has already bound to another Firefly account.')
+    }
+
+    const data = resolveFireflyResponseData(response)
+    patchFarcasterSessionRequired(session, data.fid, data.farcaster_signer_private_key)
+    return data
+}
+
+/**
+ * Bind a lens or farcaster session to the currently logged-in Firefly session.
+ * @param session
+ * @param signal
+ * @returns
+ */
+export async function bindFireflySession(session: Session, signal?: AbortSignal) {
+    // Ensure that the Firefly session is resumed before calling this function.
+    fireflySessionHolder.assertSession()
+    if (session.type === SessionType.Farcaster) {
+        return bindFarcasterSessionToFirefly(session as FarcasterSession, signal)
+    } else if (session.type === SessionType.Firefly) {
+        throw new Error('Not allowed')
+    }
+    throw new Error(`Unknown session type: ${session.type}`)
+}

packages/mask/popups/pages/Personas/ConnectFirefly/bindOrRestoreFireflySession.ts

@@ -0,0 +1,22 @@
+import { fireflySessionHolder } from '@masknet/web3-providers'
+import type { Session } from '@masknet/web3-providers/types'
+import { bindFireflySession } from './bindFireflySession'
+import { restoreFireflySession } from './restoreFireflySession'
+
+export async function bindOrRestoreFireflySession(session: Session, signal?: AbortSignal) {
+    try {
+        if (fireflySessionHolder.session) {
+            await bindFireflySession(session, signal)
+
+            // this will return the existing session
+            return fireflySessionHolder.assertSession(
+                '[bindOrRestoreFireflySession] Failed to bind farcaster session with firefly.',
+            )
+        } else {
+            throw new Error('[bindOrRestoreFireflySession] Firefly session is not available.')
+        }
+    } catch (error) {
+        // this will create a new session
+        return restoreFireflySession(session, signal)
+    }
+}

packages/mask/popups/pages/Personas/ConnectFirefly/createAccountByRelayService.ts

@@ -1,7 +1,7 @@
-import type { Account } from '@masknet/shared-base'
 import { fetchJSON } from '@masknet/web3-providers/helpers'
-import { FarcasterSession } from '@masknet/web3-providers'
+import { FarcasterSession, getFarcasterProfileById, type FireflyAccount } from '@masknet/web3-providers'
 import urlcat from 'urlcat'
+import { bindOrRestoreFireflySession } from './bindOrRestoreFireflySession'
 
 const FARCASTER_REPLY_URL = 'https://relay.farcaster.xyz'
 const NOT_DEPEND_SECRET = '[TO_BE_REPLACED_LATER]'
@@ -20,9 +20,12 @@ async function createSession(signal?: AbortSignal) {
     const url = urlcat(FARCASTER_REPLY_URL, '/v1/channel')
     const response = await fetchJSON<FarcasterReplyResponse>(url, {
         method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
         body: JSON.stringify({
-            siteUri: 'https://www.mask.io',
-            domain: 'www.mask.io',
+            siweUri: 'https://firefly.social',
+            domain: 'firefly.social',
         }),
         signal,
     })
@@ -51,6 +54,7 @@ export async function createAccountByRelayService(callback?: (url: string) => vo
 
     // polling for the session to be ready
     const fireflySession = await bindOrRestoreFireflySession(session, signal)
+    console.log('fireflySession', fireflySession)
 
     // profile id is available after the session is ready
     const profile = await getFarcasterProfileById(session.profileId)
@@ -60,5 +64,5 @@ export async function createAccountByRelayService(callback?: (url: string) => vo
         session,
         profile,
         fireflySession,
-    } satisfies Account
+    } satisfies FireflyAccount
 }

packages/mask/popups/pages/Personas/ConnectFirefly/index.tsx

@@ -1,23 +1,96 @@
-import { useLingui } from '@lingui/react/macro'
+import { Trans, useLingui } from '@lingui/react/macro'
 import { PopupHomeTabType } from '@masknet/shared'
-import { QRCode } from 'react-qrcode-logo'
-import { PopupRoutes } from '@masknet/shared-base'
-import { makeStyles } from '@masknet/theme'
+import {
+    AbortError,
+    FarcasterPatchSignerError,
+    FireflyAlreadyBoundError,
+    FireflyBindTimeoutError,
+    PopupRoutes,
+    TimeoutError,
+} from '@masknet/shared-base'
+import { makeStyles, usePopupCustomSnackbar } from '@masknet/theme'
+import { addAccount, type AccountOptions, type FireflyAccount } from '@masknet/web3-providers'
+import { Social } from '@masknet/web3-providers/types'
 import { Box } from '@mui/material'
-import { memo, useCallback } from 'react'
+import { memo, useCallback, useState } from 'react'
+import { QRCode } from 'react-qrcode-logo'
 import { useNavigate } from 'react-router-dom'
 import urlcat from 'urlcat'
 import { useTitle } from '../../../hooks/index.js'
+import { useMount } from 'react-use'
+import { createAccountByRelayService } from './createAccountByRelayService.js'
 
 const useStyles = makeStyles()({
-    container: {},
+    container: {
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
 })
 
+function useLogin() {
+    const { showSnackbar } = usePopupCustomSnackbar()
+    return useCallback(
+        async function login(createAccount: () => Promise<FireflyAccount>, options?: Omit<AccountOptions, 'source'>) {
+            try {
+                const account = await createAccount()
+
+                const done = await addAccount(account, options)
+                console.log('created account', account)
+                if (done) showSnackbar(<Trans>Your {Social.Source.Farcaster} account is now connected.</Trans>)
+            } catch (error) {
+                // skip if the error is abort error
+                if (AbortError.is(error)) return
+
+                // if login timed out, let the user refresh the QR code
+                if (error instanceof TimeoutError || error instanceof FireflyBindTimeoutError) {
+                    showSnackbar(<Trans>This QR code is longer valid. Please scan a new one to continue.</Trans>)
+                    return
+                }
+
+                // failed to patch the signer
+                if (error instanceof FarcasterPatchSignerError) throw error
+
+                // if any error occurs, close the modal
+                // by this we don't need to do error handling in UI part.
+                // if the account is already bound to another account, show a warning message
+                if (error instanceof FireflyAlreadyBoundError) {
+                    showSnackbar(
+                        <Trans>
+                            The account you are trying to log in with is already linked to a different Firefly account.
+                        </Trans>,
+                    )
+                    return
+                }
+
+                throw error
+            }
+        },
+        [showSnackbar],
+    )
+}
+
 export const Component = memo(function ConnectFireflyPage() {
     const { t } = useLingui()
     const { classes } = useStyles()
+    const [url, setUrl] = useState('')
 
     const navigate = useNavigate()
+    const login = useLogin()
+
+    useMount(async () => {
+        login(async () => {
+            try {
+                const account = await createAccountByRelayService((url) => {
+                    setUrl(url)
+                })
+                return account
+            } catch (err) {
+                console.log('error', err)
+                throw err
+            }
+        })
+    })
 
     const handleBack = useCallback(() => {
         navigate(urlcat(PopupRoutes.Personas, { tab: PopupHomeTabType.ConnectedWallets }), {
@@ -29,7 +102,7 @@ export const Component = memo(function ConnectFireflyPage() {
 
     return (
         <Box className={classes.container}>
-            <QRCode value="hello" ecLevel="L" size={220} quietZone={16} eyeRadius={100} qrStyle="dots" />
+            <QRCode value={url} ecLevel="L" size={220} quietZone={16} eyeRadius={100} qrStyle="dots" />
         </Box>
     )
 })

packages/mask/popups/pages/Personas/ConnectFirefly/restoreFireflySession.ts

@@ -0,0 +1,55 @@
+import {
+    FarcasterSession,
+    FIREFLY_ROOT_URL,
+    FireflySession,
+    patchFarcasterSessionRequired,
+    resolveFireflyResponseData,
+} from '@masknet/web3-providers'
+import type { FireflyConfigAPI, Session } from '@masknet/web3-providers/types'
+import urlcat from 'urlcat'
+
+export async function restoreFireflySessionFromFarcaster(session: FarcasterSession, signal?: AbortSignal) {
+    const isGrantByPermission = FarcasterSession.isGrantByPermission(session, true)
+    const isRelayService = FarcasterSession.isRelayService(session)
+    if (!isGrantByPermission && !isRelayService)
+        throw new Error('[restoreFireflySession] Only grant-by-permission or relay service sessions are allowed.')
+
+    const url = urlcat(FIREFLY_ROOT_URL, '/v3/auth/farcaster/login')
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            token: isGrantByPermission ? session.signerRequestToken : undefined,
+            channelToken: isRelayService ? session.channelToken : undefined,
+        }),
+        signal,
+    })
+
+    const json: FireflyConfigAPI.LoginResponse = await response.json()
+    if (!response.ok && json.error?.includes('Farcaster login timed out'))
+        throw new Error('[restoreFireflySession] Farcaster login timed out.')
+
+    const data = resolveFireflyResponseData(json)
+    if (data.fid && data.accountId && data.accessToken) {
+        patchFarcasterSessionRequired(session as FarcasterSession, data.fid, data.farcaster_signer_private_key)
+        return new FireflySession(data.uid ?? data.accountId, data.accessToken, session, null, false, data)
+    }
+    throw new Error('[restoreFireflySession] Failed to restore firefly session.')
+}
+
+/**
+ * Restore firefly session from a lens or farcaster session.
+ * @param session
+ * @param signal
+ * @returns
+ */
+export function restoreFireflySession(session: Session, signal?: AbortSignal) {
+    if (session.type === 'Farcaster') {
+        return restoreFireflySessionFromFarcaster(session as FarcasterSession, signal)
+    } else if (session.type === 'Firefly') {
+        throw new Error('[restoreFireflySession] Firefly session is not allowed.')
+    }
+    throw new Error(`[restoreFireflySession] Unknown session type: ${session.type}`)
+}

packages/plugins/RSS3/src/SiteAdaptor/SocialFeeds/SocialFeed.tsx

@@ -183,6 +183,7 @@ const useStyles = makeStyles<void, 'image' | 'markdown' | 'failedImage' | 'body'
 const PlatformIconMap = {
     [Social.Source.Farcaster]: Icons.Farcaster,
     [Social.Source.Lens]: Icons.DarkLens,
+    [Social.Source.Firefly]: null,
 }
 
 export interface SocialFeedProps extends HTMLProps<HTMLDivElement> {

packages/shared-base/src/errors.ts

@@ -0,0 +1,41 @@
+export class AbortError extends Error {
+    override name = 'AbortError'
+
+    constructor(message = 'Aborted') {
+        super(message)
+    }
+
+    static is(error: unknown) {
+        return error instanceof AbortError || (error instanceof DOMException && error.name === 'AbortError')
+    }
+}
+
+export class FarcasterPatchSignerError extends Error {
+    override name = 'FarcasterPatchSignerError'
+
+    constructor(public fid: number) {
+        super(`Failed to patch signer key to Farcaster session: ${fid}`)
+    }
+}
+
+export class TimeoutError extends Error {
+    override name = 'TimeoutError'
+
+    constructor(message?: string) {
+        super(message ?? 'Timeout.')
+    }
+}
+
+export class FireflyBindTimeoutError extends Error {
+    override name = 'FireflyBindTimeoutError'
+    constructor(public source: string) {
+        super(`Bind ${source} account to Firefly timeout.`)
+    }
+}
+export class FireflyAlreadyBoundError extends Error {
+    override name = 'FireflyAlreadyBoundError'
+
+    constructor(public source: string) {
+        super(`This ${source} account has already bound to another Firefly account.`)
+    }
+}

packages/shared-base/src/index.ts

@@ -4,6 +4,7 @@ export * from './constants.js'
 export * from './types.js'
 export * from './types/index.js'
 export * from './helpers/index.js'
+export * from './errors.js'
 
 export * from './Messages/Events.js'
 export * from './Messages/CrossIsolationEvents.js'

packages/web3-providers/src/Farcaster/getFarcasterFriendship.ts

@@ -0,0 +1,18 @@
+import urlcat from 'urlcat'
+import { FIREFLY_ROOT_URL } from '../Firefly/constants'
+import { resolveFireflyResponseData } from '../Firefly/helpers'
+import { fetchJSON } from '../helpers/fetchJSON'
+import type { FireflyConfigAPI } from '../types/Firefly'
+
+export async function getFarcasterFriendship(sourceFid: string, destFid: string) {
+    const response = await fetchJSON<FireflyConfigAPI.FriendshipResponse>(
+        urlcat(FIREFLY_ROOT_URL, '/v2/farcaster-hub/user/friendship', {
+            sourceFid,
+            destFid,
+        }),
+        {
+            method: 'GET',
+        },
+    )
+    return resolveFireflyResponseData<FireflyConfigAPI.FriendshipResponse['data']>(response)
+}