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.

2.3 KB
Raw Blame
import { ApiError } from './client'

// `APIScopePermission` in `posthog/permissions.py` answers a token without the scope with 403 and this detail. A 403
// for anything else, such as a dashboard the user cannot view, has another detail and must not ask for a new sign-in.
const MISSING_SCOPE = /missing required scope '([^']+)'/

/** The scope a 403 names as missing, such as `dashboard:read`, or null for any other error. */
export function missingScope(error: unknown): string | null {
    if (!(error instanceof ApiError) || error.status !== 403) {
        return null
    }
    return MISSING_SCOPE.exec(error.detail ?? '')?.[1] ?? null
}

/** The scopes Views needs on top of the app's others. `file_system_shortcut:write` also grants the read. */
export const VIEWS_SCOPES = ['dashboard:read', 'insight:read', 'file_system_shortcut:write'] as const

/** True when the scopes include `scope`. A `:write` scope covers the matching `:read`. */
export function coversScope(scopes: readonly string[], scope: string): boolean {
    const [object, level] = scope.split(':')
    return scopes.includes(scope) || (level === 'read' && scopes.includes(`${object}:write`))
}

/** The scopes the issues list and issue screen need. The write covers status and assignee changes. */
export const ERRORS_SCOPES = ['error_tracking:read', 'error_tracking:write'] as const

/** The scopes the sessions list and session screen need. `replay_scanner` covers the AI summary. */
export const REPLAY_SCOPES = ['session_recording:read', 'replay_scanner:read', 'replay_scanner:write'] as const

export type ScopedFeature = 'views' | 'errors' | 'replay' | 'inbox'

export const FEATURE_SCOPES: Record<ScopedFeature, readonly string[]> = {
    views: VIEWS_SCOPES,
    errors: ERRORS_SCOPES,
    replay: REPLAY_SCOPES,
    inbox: ['inbox:read', 'inbox:write'],
}

/** The first scope of `feature` a grant lacks, or null for an unknown grant. */
export function missingFeatureScope(granted: readonly string[] | null, feature: ScopedFeature): string | null {
    if (!granted) {
        return null
    }
    return FEATURE_SCOPES[feature].find((scope) => !coversScope(granted, scope)) ?? null
}

/** The first Views scope a grant lacks, or null for an unknown grant. */
export function missingViewsScope(granted: readonly string[] | null): string | null {
    return missingFeatureScope(granted, 'views')
}