feat: add firefly session management and farcaster integration

Author: swkatmask

.node-version

@@ -1 +1 @@
-v23.6.0
+v24.7.0

cspell.json

@@ -263,6 +263,7 @@
         "boba",
         "cashtags",
         "celo",
+        "deeplink",
         "endregion",
         "firelfy",
         "linkedin",
@@ -276,6 +277,7 @@
         "tweetnacl",
         "txid",
         "waitlist",
+        "WARPCAST",
         "youtube"
     ]
 }

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

@@ -0,0 +1,64 @@
+import type { Account } from '@masknet/shared-base'
+import { fetchJSON } from '@masknet/web3-providers/helpers'
+import { FarcasterSession } from '@masknet/web3-providers'
+import urlcat from 'urlcat'
+
+const FARCASTER_REPLY_URL = 'https://relay.farcaster.xyz'
+const NOT_DEPEND_SECRET = '[TO_BE_REPLACED_LATER]'
+
+interface FarcasterReplyResponse {
+    channelToken: string
+    url: string
+    // the same as url
+    connectUri: string
+    // cspell: disable-next-line
+    /** @example dpO7VRkrPcwyLhyFZ */
+    nonce: string
+}
+
+async function createSession(signal?: AbortSignal) {
+    const url = urlcat(FARCASTER_REPLY_URL, '/v1/channel')
+    const response = await fetchJSON<FarcasterReplyResponse>(url, {
+        method: 'POST',
+        body: JSON.stringify({
+            siteUri: 'https://www.mask.io',
+            domain: 'www.mask.io',
+        }),
+        signal,
+    })
+
+    const now = Date.now()
+    const farcasterSession = new FarcasterSession(
+        NOT_DEPEND_SECRET,
+        NOT_DEPEND_SECRET,
+        now,
+        now,
+        '',
+        response.channelToken,
+    )
+
+    return {
+        deeplink: response.connectUri,
+        session: farcasterSession,
+    }
+}
+
+export async function createAccountByRelayService(callback?: (url: string) => void, signal?: AbortSignal) {
+    const { deeplink, session } = await createSession(signal)
+
+    // present QR code to the user or open the link in a new tab
+    callback?.(deeplink)
+
+    // polling for the session to be ready
+    const fireflySession = await bindOrRestoreFireflySession(session, signal)
+
+    // profile id is available after the session is ready
+    const profile = await getFarcasterProfileById(session.profileId)
+
+    return {
+        origin: 'sync',
+        session,
+        profile,
+        fireflySession,
+    } satisfies Account
+}

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

@@ -0,0 +1,108 @@
+import urlcat from 'urlcat'
+
+import { SessionType, type Session } from '../types/Session.js'
+import { fetchJSON } from '../helpers/fetchJSON.js'
+import { BaseSession } from '../Session/Session.js'
+
+export const WARPCAST_ROOT_URL_V2 = 'https://api.warpcast.com/v2'
+export const FAKE_SIGNER_REQUEST_TOKEN = 'fake_signer_request_token'
+
+export enum FarcasterSponsorship {
+    Firefly = 'firefly',
+}
+
+export class FarcasterSession extends BaseSession implements Session {
+    constructor(
+        /**
+         * Fid
+         */
+        profileId: string,
+        /**
+         * the private key of the signer
+         */
+        token: string,
+        createdAt: number,
+        expiresAt: number,
+        public signerRequestToken?: string,
+        public channelToken?: string,
+        public sponsorshipSignature?: string,
+        public walletAddress?: string,
+    ) {
+        super(SessionType.Farcaster, profileId, token, createdAt, expiresAt)
+    }
+
+    override serialize(): `${SessionType}:${string}:${string}:${string}` {
+        return [
+            super.serialize(),
+            this.signerRequestToken ?? '',
+            this.channelToken ?? '',
+            this.sponsorshipSignature ?? '',
+        ].join(':') as `${SessionType}:${string}:${string}:${string}`
+    }
+
+    refresh(): Promise<void> {
+        throw new Error('Not allowed')
+    }
+
+    async destroy(): Promise<void> {
+        const url = urlcat(WARPCAST_ROOT_URL_V2, '/auth')
+        const response = await fetchJSON<{
+            result: {
+                success: boolean
+            }
+        }>(url, {
+            method: 'DELETE',
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+            },
+            body: JSON.stringify({
+                method: 'revokeToken',
+                params: {
+                    timestamp: this.createdAt,
+                },
+            }),
+        })
+
+        // indicate the session is destroyed
+        this.expiresAt = 0
+
+        if (!response.result.success) throw new Error('Failed to destroy the session.')
+        return
+    }
+
+    static isGrantByPermission(
+        session: Session | null,
+        // if strict is true, the session must have a valid signer request token
+        strict = false,
+    ): session is FarcasterSession & { signerRequestToken: string } {
+        if (!session) return false
+        const token = (session as FarcasterSession).signerRequestToken
+        return (
+            session.type === SessionType.Farcaster &&
+            !!token &&
+            // strict mode
+            (strict ? token !== FAKE_SIGNER_REQUEST_TOKEN : true)
+        )
+    }
+
+    static isSponsorship(
+        session: Session | null,
+        strict = false,
+    ): session is FarcasterSession & { signerRequestToken: string; sponsorshipSignature: string } {
+        if (!session) return false
+        return (
+            FarcasterSession.isGrantByPermission(session, strict) &&
+            !!(session as FarcasterSession).sponsorshipSignature
+        )
+    }
+
+    static isRelayService(session: Session | null): session is FarcasterSession & { channelToken: string } {
+        if (!session) return false
+        return session.type === 'Farcaster' && !!(session as FarcasterSession).channelToken
+    }
+
+    static isLoginByWallet(session: Session | null): session is FarcasterSession & { walletAddress: string } {
+        if (!session) return false
+        return session.type === 'Farcaster' && !!(session as FarcasterSession).walletAddress
+    }
+}

packages/web3-providers/src/Firefly/FarcasterSession.ts

@@ -0,0 +1,82 @@
+import { BaseSession } from '../Session/Session'
+import { SessionType, type Session } from '../types/Session'
+
+export const WARPCAST_ROOT_URL_V2 = 'https://api.warpcast.com/v2'
+export const FAKE_SIGNER_REQUEST_TOKEN = 'fake_signer_request_token'
+
+export enum FarcasterSponsorship {
+    Firefly = 'firefly',
+}
+
+export type FireflySessionSignature = {
+    address: string
+    message: string
+    signature: string
+}
+
+export type FireflySessionPayload = {
+    /**
+     * indicate a new firefly binding when it was created
+     */
+    isNew?: boolean
+
+    /**
+     * numeric user ID
+     */
+    uid?: string
+    /**
+     * UUID of the user
+     */
+    accountId?: string
+    avatar?: string | null
+    displayName?: string | null
+}
+
+export class FireflySession extends BaseSession implements Session {
+    constructor(
+        accountId: string,
+        accessToken: string,
+        public parent: Session | null,
+        public signature: FireflySessionSignature | null,
+        /**
+         * @deprecated
+         * This field always false. Use `payload.isNew` instead
+         */
+        public isNew?: boolean,
+        public payload?: FireflySessionPayload,
+    ) {
+        super(SessionType.Firefly, accountId, accessToken, 0, 0)
+    }
+
+    /**
+     * For users after this patch use accountId in UUID format for events.
+     * For legacy users use profileId in numeric format for events.
+     */
+    get accountIdForEvent() {
+        return this.payload?.accountId ?? this.profileId
+    }
+
+    override serialize(): `${SessionType}:${string}:${string}:${string}` {
+        return [
+            super.serialize(),
+            // parent session
+            this.parent ? btoa(this.parent.serialize()) : '',
+            // signature if session created by signing a message
+            this.signature ? encodeAsciiPayload(this.signature) : '',
+            // isNew flag
+            this.isNew ? '1' : '0',
+            // extra data payload
+            this.payload ? encodeNoAsciiPayload(this.payload) : '',
+        ].join(':') as `${SessionType}:${string}:${string}:${string}`
+    }
+
+    override async refresh(): Promise<void> {
+        // throw new NotAllowedError()
+        throw new Error('Not allowed')
+    }
+
+    override async destroy(): Promise<void> {
+        // throw new NotAllowedError()
+        throw new Error('Not allowed')
+    }
+}

packages/web3-providers/src/Firefly/Session.ts

@@ -0,0 +1,34 @@
+import type { NextFetchersOptions } from '@/helpers/getNextFetchers.js'
+import type { FireflySession } from './Session.js'
+import { fetchJSON } from '../helpers/fetchJSON.js'
+import { SessionHolder } from '../Session/SessionHolder.js'
+
+class FireflySessionHolder extends SessionHolder<FireflySession> {
+    fetchWithSessionGiven(session: FireflySession) {
+        return <T>(url: string, init?: RequestInit) => {
+            return fetchJSON<T>(url, {
+                ...init,
+                headers: { ...init?.headers, Authorization: `Bearer ${session.token}` },
+            })
+        }
+    }
+
+    override async fetchWithSession<T>(url: string, init?: RequestInit, options?: NextFetchersOptions) {
+        const authToken = this.sessionRequired.token
+
+        return fetchJSON<T>(
+            url,
+            {
+                ...init,
+                headers: { ...init?.headers, Authorization: `Bearer ${authToken}` },
+            },
+            options,
+        )
+    }
+
+    override fetchWithoutSession<T>(url: string, init?: RequestInit, options?: NextFetchersOptions) {
+        return fetchJSON<T>(url, init, options)
+    }
+}
+
+export const fireflySessionHolder = new FireflySessionHolder()

packages/web3-providers/src/Firefly/SessionHolder.ts

@@ -2,4 +2,6 @@ export * from './Config.js'
 export * from './RedPacket.js'
 export * from './Twitter.js'
 export * from './Farcaster.js'
+export * from './Session.js'
+export * from './FarcasterSession.js'
 export { FIREFLY_SITE_URL } from './constants.js'

packages/web3-providers/src/Firefly/index.ts

@@ -0,0 +1,27 @@
+import { type SessionType, type Session } from '../types/Session.js'
+
+export abstract class BaseSession implements Session {
+    constructor(
+        public type: SessionType,
+        public profileId: string,
+        public token: string,
+        public createdAt: number,
+        public expiresAt: number,
+    ) {}
+
+    serialize(): `${SessionType}:${string}` {
+        const body = JSON.stringify({
+            type: this.type,
+            token: this.token,
+            profileId: this.profileId,
+            createdAt: this.createdAt,
+            expiresAt: this.expiresAt,
+        })
+
+        return `${this.type}:${btoa(body)}`
+    }
+
+    abstract refresh(): Promise<void>
+
+    abstract destroy(): Promise<void>
+}