Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

24.7 KB
Raw Blame
import AsyncStorage from '@react-native-async-storage/async-storage'
import { AppState, type NativeEventSubscription } from 'react-native'
import { create } from 'zustand'
import { createJSONStorage, persist } from 'zustand/middleware'

import { ApiError, NotSignedInError, setAuthProvider } from '@/api/client'
import { queryClient } from '@/api/queryClient'
import { TransportError } from '@/api/transport'
import { identify, resetAnalytics, track } from '@/lib/analytics'
import { toError } from '@/lib/errors'
import { createPersistHydrationGate } from '@/lib/persistHydration'

import {
    type Account,
    type AuthOrganization,
    type AuthProject,
    type AuthUser,
    loadAccount,
    loadAccountWithCredentials,
    pickProjectId,
} from './account'
import { authorize, OAuthError, refreshTokens, revokeToken } from './oauth'
import { type RegionId, regionForHost, validateHost } from './regions'
import { AccountLoadError, accountLoadKind, SignInInputError } from './signInErrors'
import {
    clearTokens,
    commitSessionTokens,
    getSessionIdentity,
    getSessionTokens,
    loadTokens,
    type SessionTokens,
    saveRefreshedTokens,
    sessionGeneration,
    setSessionTokens,
} from './tokens'

export type { AuthOrganization, AuthProject, AuthUser } from './account'

export type AuthStatus = 'loading' | 'signed_out' | 'signed_in'
export type AuthMethod = 'oauth' | 'personal_api_key'
export type ProjectSwitchSource = 'nav_menu' | 'settings' | 'push'

export interface AuthState {
    status: AuthStatus
    signedIn: boolean
    /** The region of the last sign-in. Kept after sign out so the sign-in screen starts there. */
    region: RegionId
    host: string | null
    clientId: string | null
    method: AuthMethod | null
    user: AuthUser | null
    organizations: AuthOrganization[]
    projects: AuthProject[]
    projectId: number | null
    projectName: string | null
    accountLoading: boolean
    accountError: string | null
    signedOutReason: 'expired' | null
    restore: () => Promise<void>
    signIn: (host: string, clientId: string) => Promise<void>
    /** Development builds only. The personal API key never refreshes. */
    signInWithPersonalApiKey: (host: string, key: string) => Promise<void>
    selectProject: (projectId: number, from: ProjectSwitchSource) => void
    reloadAccount: () => Promise<void>
    signOut: () => Promise<void>
}

const RESTORE_REFRESH_MARGIN_MS = 60_000

/** Refresh at launch or on foreground when the access token has less than this left, so the home screen widget's copy stays valid. */
const FOREGROUND_REFRESH_MARGIN_MS = 24 * 60 * 60_000

type SignOutTask = () => Promise<undefined | (() => void)>
type SessionEndTask = () => void | Promise<void>

const signOutTasks = new Set<SignOutTask>()
const sessionEndTasks = new Set<SessionEndTask>()

/** Registers work that must run while the session is still valid, before sign out drops the token. */
export function addSignOutTask(task: SignOutTask): () => void {
    signOutTasks.add(task)
    return () => {
        signOutTasks.delete(task)
    }
}

/**
 * Registers device cleanup for every end of a session: sign out and a session that expired. It runs after the token
 * is gone, so it must not call the API. Features use it to drop per-user state without the auth store importing them.
 */
export function addSessionEndTask(task: SessionEndTask): () => void {
    sessionEndTasks.add(task)
    return () => {
        sessionEndTasks.delete(task)
    }
}

const SIGNED_OUT_ACCOUNT = {
    status: 'signed_out',
    signedIn: false,
    method: null,
    user: null,
    organizations: [],
    projects: [],
    projectId: null,
    projectName: null,
    accountLoading: false,
    accountError: null,
} satisfies Partial<AuthState>

function projectNameFor(projects: AuthProject[], projectId: number | null): string | null {
    return projects.find((project) => project.id === projectId)?.name ?? null
}

function accountLoadMessage(error: unknown, method: AuthMethod): string {
    if (error instanceof NotSignedInError) {
        return method === 'personal_api_key'
            ? "PostHog didn't accept that key. Check that it is a personal API key with the user:read, organization:read and project:read scopes."
            : "PostHog didn't accept the new session. Try signing in again."
    }
    if (error instanceof ApiError && error.status === 403) {
        return `PostHog didn't share your account details with the app. ${error.detail ?? 'Check the key or app scopes and try again.'}`
    }
    if (error instanceof ApiError) {
        return `Couldn't load your account. ${error.message}`
    }
    if (error instanceof TransportError) {
        return error.message
    }
    return toError(error).message
}

/** In-flight work that callers of one session share. A caller from another session starts its own. */
interface SessionTask<T> {
    session: number
    promise: Promise<T>
}

let restoring: Promise<void> | null = null
let reloading: SessionTask<void> | null = null
let refreshing: SessionTask<string | null> | null = null
let signInIntent = 0
let sessionTransitions: Promise<void> = Promise.resolve()
const hydration = createPersistHydrationGate()

function serializeSessionTransition<T>(work: () => Promise<T>): Promise<T> {
    const result = sessionTransitions.then(work, work)
    sessionTransitions = result.then(
        () => undefined,
        () => undefined
    )
    return result
}

async function runSignOutTasks(): Promise<(() => void)[]> {
    const recoveries: (() => void)[] = []
    try {
        for (const task of signOutTasks) {
            const recover = await task()
            if (recover) {
                recoveries.push(recover)
            }
        }
        return recoveries
    } catch (error) {
        for (const recover of recoveries) {
            recover()
        }
        throw error
    }
}

export const useAuthStore = create<AuthState>()(
    persist(
        (set, get) => {
            const accountFields = (account: Account, preferProjectId: number | null): Partial<AuthState> => {
                const projectId = pickProjectId(account.projects, [preferProjectId, account.webTeamId])
                return {
                    user: account.user,
                    organizations: account.organizations,
                    projects: account.projects,
                    projectId,
                    projectName: projectNameFor(account.projects, projectId),
                    accountError: null,
                }
            }

            const applyAccount = (account: Account, preferProjectId: number | null): void => {
                set(accountFields(account, preferProjectId))
            }

            const completeSignIn = async (
                tokens: SessionTokens,
                method: AuthMethod,
                host: string,
                clientId: string | null,
                intent: number
            ): Promise<void> => {
                let account: Account
                try {
                    account = await loadAccountWithCredentials(host, tokens.accessToken)
                } catch (error) {
                    throw new AccountLoadError(accountLoadKind(error), accountLoadMessage(error, method))
                }
                await serializeSessionTransition(async () => {
                    if (intent !== signInIntent) {
                        throw new OAuthError('cancelled')
                    }
                    const previous = get()
                    const previousSession = sessionGeneration()
                    let recoveries: (() => void)[] = []
                    if (previous.status === 'signed_in') {
                        recoveries = await runSignOutTasks()
                    }
                    try {
                        if (intent !== signInIntent) {
                            throw new OAuthError('cancelled')
                        }
                        if (previous.status === 'signed_in') {
                            await Promise.allSettled([...sessionEndTasks].map(async (task) => task()))
                        }
                        const previousTokens = getSessionTokens()
                        const region = regionForHost(host)
                        const committed = await commitSessionTokens(
                            tokens,
                            { host, clientId, method, userUuid: account.user.uuid },
                            () => intent === signInIntent && sessionGeneration() === previousSession,
                            () => {
                                queryClient.clear()
                                const preferProjectId =
                                    previous.user?.uuid === account.user.uuid ? previous.projectId : null
                                set({
                                    ...accountFields(account, preferProjectId),
                                    status: 'signed_in',
                                    signedIn: true,
                                    region,
                                    host,
                                    clientId,
                                    method,
                                    signedOutReason: null,
                                })
                            }
                        )
                        if (!committed) {
                            throw new OAuthError('cancelled')
                        }
                        if (previous.status === 'signed_in') {
                            queryClient.clear()
                        }
                        identify(account.user.distinctId)
                        track('mobile_signed_in', { method, region })
                        if (
                            previousTokens?.kind === 'oauth' &&
                            previousTokens.refreshToken &&
                            previous.host &&
                            previous.clientId
                        ) {
                            void revokeToken({
                                host: previous.host,
                                clientId: previous.clientId,
                                token: previousTokens.refreshToken,
                            })
                        }
                    } catch (error) {
                        if (sessionGeneration() === previousSession) {
                            for (const recover of recoveries) {
                                recover()
                            }
                        }
                        throw error
                    }
                })
            }

            return {
                status: 'loading',
                signedIn: false,
                region: 'us',
                host: null,
                clientId: null,
                method: null,
                user: null,
                organizations: [],
                projects: [],
                projectId: null,
                projectName: null,
                accountLoading: false,
                accountError: null,
                signedOutReason: null,

                restore: () => {
                    restoring ??= (async () => {
                        await waitForHydration()
                        const tokens = await loadTokens()
                        const owner = getSessionIdentity()
                        if (!tokens || !owner || !validateHost(owner.host).ok) {
                            setSessionTokens(null)
                            set(SIGNED_OUT_ACCOUNT)
                            return
                        }
                        const metadata = get()
                        const sameAccount =
                            metadata.host === owner.host &&
                            metadata.clientId === owner.clientId &&
                            metadata.method === owner.method &&
                            metadata.user?.uuid === owner.userUuid
                        set({
                            ...(!sameAccount ? SIGNED_OUT_ACCOUNT : {}),
                            status: 'loading',
                            signedIn: false,
                            host: owner.host,
                            clientId: owner.clientId,
                            method: owner.method,
                            region: regionForHost(owner.host),
                        })
                        let refreshedDuringRestore = false
                        if (
                            tokens.kind === 'oauth' &&
                            tokens.expiresAt !== null &&
                            tokens.expiresAt - Date.now() < RESTORE_REFRESH_MARGIN_MS
                        ) {
                            refreshedDuringRestore = true
                            try {
                                if ((await refreshAccessToken()) === null) {
                                    return
                                }
                            } catch {
                                // Offline or a server error: keep the session. The next 401 retries the refresh.
                            }
                        }
                        const { user } = get()
                        if (!user) {
                            await get().reloadAccount()
                        }
                        set({ status: 'signed_in', signedIn: true })
                        if (!refreshedDuringRestore && AppState.currentState === 'active') {
                            refreshBeforeForegroundMargin()
                        }
                        const restored = get().user
                        if (restored) {
                            identify(restored.distinctId)
                        }
                        track('mobile_session_restored', { method: get().method })
                        if (user) {
                            void get().reloadAccount()
                        }
                    })()
                    return restoring
                },

                signIn: async (host, clientId) => {
                    const validation = validateHost(host)
                    if (!validation.ok) {
                        throw new SignInInputError(validation.error)
                    }
                    const trimmedClientId = clientId.trim()
                    if (!trimmedClientId) {
                        throw new SignInInputError('Enter the OAuth client ID of the PostHog app on this instance.')
                    }
                    const intent = ++signInIntent
                    const tokens = await authorize({ host: validation.host, clientId: trimmedClientId })
                    try {
                        await completeSignIn(tokens, 'oauth', validation.host, trimmedClientId, intent)
                    } catch (error) {
                        if (tokens.refreshToken) {
                            void revokeToken({
                                host: validation.host,
                                clientId: trimmedClientId,
                                token: tokens.refreshToken,
                            })
                        }
                        throw error
                    }
                },

                signInWithPersonalApiKey: async (host, key) => {
                    if (!__DEV__) {
                        throw new SignInInputError('Personal API keys only work in development builds.')
                    }
                    const validation = validateHost(host)
                    if (!validation.ok) {
                        throw new SignInInputError(validation.error)
                    }
                    const trimmedKey = key.trim()
                    if (!trimmedKey) {
                        throw new SignInInputError('Paste a personal API key.')
                    }
                    const intent = ++signInIntent
                    await completeSignIn(
                        {
                            kind: 'personal_api_key',
                            accessToken: trimmedKey,
                            refreshToken: null,
                            expiresAt: null,
                            grantedScopes: null,
                            requestedScopes: null,
                        },
                        'personal_api_key',
                        validation.host,
                        null,
                        intent
                    )
                },

                selectProject: (projectId, from) => {
                    const { projects, projectId: current } = get()
                    const project = projects.find((candidate) => candidate.id === projectId)
                    if (!project || projectId === current) {
                        return
                    }
                    set({ projectId, projectName: project.name })
                    track('mobile_project_switched', { from })
                    // Every cached query belongs to the previous project. Reset drops the data, so no
                    // screen shows the old project's reports, and refetches what is on screen.
                    void queryClient.resetQueries()
                },

                reloadAccount: () => {
                    const session = sessionGeneration()
                    if (reloading?.session === session) {
                        return reloading.promise
                    }
                    const promise = (async (): Promise<void> => {
                        if (get().status === 'signed_out') {
                            return
                        }
                        set({ accountLoading: true })
                        try {
                            const account = await loadAccount()
                            // The account belongs to the earlier session. The new session loads its own.
                            if (sessionGeneration() !== session) {
                                return
                            }
                            const before = get().projectId
                            applyAccount(account, before)
                            if (before !== null && get().projectId !== before) {
                                void queryClient.resetQueries()
                            }
                            set({ accountLoading: false })
                        } catch (error) {
                            // The failure belongs to the earlier session, so it must not show on the new one.
                            if (sessionGeneration() !== session) {
                                return
                            }
                            if (error instanceof NotSignedInError) {
                                set({ accountLoading: false })
                                return
                            }
                            set({
                                accountLoading: false,
                                accountError: accountLoadMessage(error, get().method ?? 'oauth'),
                            })
                            track('mobile_account_reload_failed', { reason: accountLoadKind(error) })
                        }
                    })().finally(() => {
                        if (reloading?.promise === promise) {
                            reloading = null
                        }
                    })
                    reloading = { session, promise }
                    return promise
                },

                signOut: async () => {
                    ++signInIntent
                    await serializeSessionTransition(async () => {
                        const { host, clientId, status } = get()
                        if (status === 'signed_out') {
                            return
                        }
                        if (status === 'signed_in') {
                            await runSignOutTasks()
                        }
                        const tokens = getSessionTokens()
                        if (tokens?.kind === 'oauth' && tokens.refreshToken && host && clientId) {
                            await revokeToken({ host, clientId, token: tokens.refreshToken })
                        }
                        await endSession('user')
                    })
                },
            }
        },
        {
            name: 'posthog-mobile-auth',
            version: 1,
            storage: createJSONStorage(() => AsyncStorage),
            partialize: (state) => ({
                region: state.region,
                host: state.host,
                clientId: state.clientId,
                method: state.method,
                user: state.user,
                organizations: state.organizations,
                projects: state.projects,
                projectId: state.projectId,
                projectName: state.projectName,
            }),
            onRehydrateStorage: () => () => hydration.settle(),
        }
    )
)

function waitForHydration(): Promise<void> {
    return hydration.wait()
}

async function endSession(reason: 'user' | 'expired'): Promise<void> {
    // Before the reset, so the event belongs to the user who signed out.
    track('mobile_signed_out', { reason, method: useAuthStore.getState().method })
    reloading = null
    refreshing = null
    await clearTokens()
    queryClient.clear()
    resetAnalytics()
    await Promise.allSettled([...sessionEndTasks].map(async (task) => task()))
    useAuthStore.setState({ ...SIGNED_OUT_ACCOUNT, signedOutReason: reason === 'expired' ? 'expired' : null })
}

async function refreshOnce(): Promise<string | null> {
    const session = sessionGeneration()
    const { status, host, clientId } = useAuthStore.getState()
    const tokens = getSessionTokens()
    // A 401 during sign in means the new credentials are bad. Sign in reports that itself.
    if (status === 'signed_out' || !tokens) {
        return null
    }
    if (!tokens.refreshToken || !host || !clientId) {
        await endSession('expired')
        return null
    }
    let next: SessionTokens
    try {
        next = await refreshTokens({
            host,
            clientId,
            refreshToken: tokens.refreshToken,
            grantedScopes: tokens.grantedScopes,
            requestedScopes: tokens.requestedScopes,
        })
    } catch (error) {
        // A rejection from the earlier host says nothing about the current session, so it must not end it.
        if (sessionGeneration() !== session) {
            return null
        }
        if (error instanceof OAuthError && error.kind === 'session_expired') {
            await endSession('expired')
            return null
        }
        if (error instanceof OAuthError && error.kind === 'network') {
            throw new TransportError()
        }
        throw error
    }
    if (sessionGeneration() !== session) {
        // The user signed out or in again while the refresh was in flight. The caller sends the result to the
        // earlier host, so it gets no token. The rotated refresh token is valid at that host but stored nowhere,
        // so revoke it there.
        if (next.refreshToken) {
            void revokeToken({ host, clientId, token: next.refreshToken })
        }
        return null
    }
    return (await saveRefreshedTokens(next, session)) ? next.accessToken : null
}

// Concurrent callers share one request, because each refresh rotates the token and a second request with the old
// one would race it. A caller from a later session never joins, because the earlier refresh returns no token.
export function refreshAccessToken(): Promise<string | null> {
    const session = sessionGeneration()
    if (refreshing?.session === session) {
        return refreshing.promise
    }
    const promise = refreshOnce().finally(() => {
        if (refreshing?.promise === promise) {
            refreshing = null
        }
    })
    refreshing = { session, promise }
    return promise
}

function refreshBeforeForegroundMargin(): void {
    const tokens = getSessionTokens()
    if (
        useAuthStore.getState().status !== 'signed_in' ||
        tokens?.kind !== 'oauth' ||
        tokens.expiresAt === null ||
        tokens.expiresAt - Date.now() >= FOREGROUND_REFRESH_MARGIN_MS
    ) {
        return
    }
    // Offline or a server error keeps the session; the next foreground or 401 tries again.
    refreshAccessToken().catch(() => undefined)
}

let foregroundSubscription: NativeEventSubscription | null = null

export function installAuthProvider(): void {
    foregroundSubscription?.remove()
    foregroundSubscription = AppState.addEventListener('change', (state) => {
        if (state === 'active') {
            refreshBeforeForegroundMargin()
        }
    })
    setAuthProvider({
        getAuth: () => {
            const state = useAuthStore.getState()
            return {
                host: state.host ?? '',
                accessToken: getSessionTokens()?.accessToken ?? null,
                projectId: state.projectId,
                session: sessionGeneration(),
            }
        },
        refreshAccessToken,
    })
}