: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import posthog from 'posthog-js'
import type { LemonSelectOptionLeaf } from '@posthog/lemon-ui'
import { getAppContext } from 'lib/utils/getAppContext'
import { capitalizeFirstLetter, toSentenceCase } from 'lib/utils/strings'
import { Scene, sceneToAccessControlResourceType } from 'scenes/sceneTypes'
import { APIScopeObject, AccessControlLevel, AccessControlResourceType, AvailableFeature } from '~/types'
import { AccessLevelEnumApi } from 'products/access_control/frontend/generated/api.schemas'
/** Property access levels with their user-facing labels, shared by the property definition page
* and the access control settings panels. */
export const PROPERTY_ACCESS_LEVEL_OPTIONS: LemonSelectOptionLeaf<AccessLevelEnumApi>[] = [
{ value: AccessLevelEnumApi.ReadWrite, label: 'Read & write' },
{ value: AccessLevelEnumApi.Read, label: 'Read only' },
{ value: AccessLevelEnumApi.None, label: 'No access' },
]
/** Which iteration of the access control settings UI an interaction came from. */
export type AccessControlUIVersion = 'v1' | 'v2'
export const toAccessControlLevel = (value: string | null | undefined): AccessControlLevel => {
switch (value) {
case AccessControlLevel.None:
case AccessControlLevel.Viewer:
case AccessControlLevel.Editor:
case AccessControlLevel.Manager:
case AccessControlLevel.Member:
case AccessControlLevel.Admin:
return value
default:
return AccessControlLevel.None
}
}
/**
* Capture an access control analytics event. All events are tagged with
* `platform_feature: ACCESS_CONTROL` so usage of the feature can be grouped and
* filtered together, matching the tagging used elsewhere (e.g. RestrictedArea).
*/
export const captureAccessControlEvent = (event: string, properties?: Record<string, unknown>): void => {
posthog.capture(event, {
...properties,
platform_feature: AvailableFeature.ACCESS_CONTROL,
})
}
/**
* Returns the minimum allowed access level for a resource.
* Matches the backend minimum_access_level function in user_access_control.py
*
* @param resource - The API scope object to check minimum access for
* @returns The minimum access level required, or null if no minimum is set
*/
export const getMinimumAccessLevel = (resource: APIScopeObject): AccessControlLevel | null => {
if (resource === 'action') {
return AccessControlLevel.Viewer
}
return null
}
/**
* Returns the maximum allowed access level for a resource.
* Matches the backend maximum_access_level function in user_access_control.py
*
* @param resource - The API scope object to check maximum access for
* @returns The maximum access level required, or null if no maximum is set
*/
export const getMaximumAccessLevel = (resource: APIScopeObject): AccessControlLevel | null => {
if (resource === AccessControlResourceType.ActivityLog || resource === AccessControlResourceType.Toolbar) {
return AccessControlLevel.Viewer
}
return null
}
/** Resources whose REST collection route doesn't match the naive `${resource}s` pluralization. */
const RESOURCE_API_ROUTES: Partial<Record<APIScopeObject, string>> = {
warehouse_view: 'warehouse_saved_queries',
early_access_feature: 'early_access_feature',
ticket: 'conversations/tickets',
heatmap: 'saved',
replay_scanner: 'vision/scanners',
}
/** REST collection route for a resource, for building `.../{route}/{id}/access_controls` urls. */
export const resourceToApiRoute = (resource: APIScopeObject): string => RESOURCE_API_ROUTES[resource] ?? `${resource}s`
/**
* Converts a resource name to its plural form for display purposes.
* Handles special cases for specific resources that have custom plural forms.
*
* @param resource - The API scope object to pluralize
* @returns The pluralized resource name for display
*/
export const pluralizeResource = (resource: APIScopeObject): string => {
if (resource === AccessControlResourceType.CustomerAnalytics) {
return 'customer analytics'
} else if (resource === AccessControlResourceType.LlmAnalytics) {
return 'AI observability'
} else if (resource === AccessControlResourceType.McpAnalytics) {
return 'MCP analytics'
} else if (resource === AccessControlResourceType.LlmSkill) {
return 'skills'
} else if (resource === AccessControlResourceType.AiObservabilityClusters) {
return 'AI trace clusters'
} else if (resource === AccessControlResourceType.RevenueAnalytics) {
return 'revenue analytics'
} else if (resource === AccessControlResourceType.WebAnalytics) {
return 'web analytics'
} else if (resource === AccessControlResourceType.MarketingAnalytics) {
return 'marketing analytics'
} else if (resource === AccessControlResourceType.ActivityLog) {
return 'activity logs'
} else if (resource === AccessControlResourceType.ExternalDataSource) {
return 'data warehouse sources'
} else if (resource === AccessControlResourceType.ErrorTracking) {
return 'error tracking'
} else if (resource === AccessControlResourceType.WarehouseObjects) {
// Umbrella label for warehouse tables + views (both inherit from this)
return 'data warehouse tables & views'
} else if (resource === AccessControlResourceType.Logs) {
return 'logs'
} else if (resource === AccessControlResourceType.Metrics) {
return 'metrics'
} else if (resource === AccessControlResourceType.Tracing) {
return 'tracing'
} else if (resource === AccessControlResourceType.SharingConfiguration) {
return 'sharing'
} else if (resource === AccessControlResourceType.Stamphog) {
// Product name, so it does not take a plural
return 'stamphog'
} else if (resource === AccessControlResourceType.Toolbar) {
return 'toolbar'
} else if (resource === AccessControlResourceType.LlmPlayground) {
return 'LLM playground'
} else if (resource === AccessControlResourceType.Workflow) {
return 'workflows'
} else if (resource === AccessControlResourceType.Ticket) {
return 'support'
} else if (resource === AccessControlResourceType.ReplayScanner) {
// Replay vision is the product name users know for scanners.
return 'replay vision'
} else if (resource === AccessControlResourceType.BusinessKnowledge) {
return 'business knowledge'
}
return resource.replace(/_/g, ' ') + 's'
}
/** Label for a resource in access control lists, e.g. "Marketing analytics". */
export const resourceLabel = (resource: APIScopeObject): string => capitalizeFirstLetter(pluralizeResource(resource))
/**
* Returns the ordered list of access levels available for a given resource type.
* Different resource types have different sets of available access levels.
*
* @param resourceType - The type of resource to get access levels for
* @returns Array of access levels ordered from lowest to highest
*/
export const orderedAccessLevels = (resourceType: AccessControlResourceType): AccessControlLevel[] => {
if (resourceType === AccessControlResourceType.Project || resourceType === AccessControlResourceType.Organization) {
return [AccessControlLevel.None, AccessControlLevel.Member, AccessControlLevel.Admin]
}
if (resourceType === AccessControlResourceType.ActivityLog || resourceType === AccessControlResourceType.Toolbar) {
return [AccessControlLevel.None, AccessControlLevel.Viewer]
}
return [AccessControlLevel.None, AccessControlLevel.Viewer, AccessControlLevel.Editor, AccessControlLevel.Manager]
}
/**
* Converts a resource type enum to a human-readable string.
* Handles special cases for specific resource types that have custom display names.
*
* @param resourceType - The access control resource type to convert
* @returns Human-readable string representation of the resource type
*/
export const resourceTypeToString = (resourceType: AccessControlResourceType): string => {
if (resourceType === AccessControlResourceType.CustomerAnalytics) {
return 'customer analytics resource'
} else if (resourceType === AccessControlResourceType.LlmAnalytics) {
return 'AI observability resource'
} else if (resourceType === AccessControlResourceType.LlmSkill) {
return 'skill'
} else if (resourceType === AccessControlResourceType.LlmPlayground) {
return 'LLM playground'
} else if (resourceType === AccessControlResourceType.AiObservabilityClusters) {
return 'AI trace clusters resource'
} else if (resourceType === AccessControlResourceType.RevenueAnalytics) {
return 'revenue analytics resource'
} else if (resourceType === AccessControlResourceType.WebAnalytics) {
return 'web analytics resource'
} else if (resourceType === AccessControlResourceType.MarketingAnalytics) {
return 'marketing analytics resource'
} else if (resourceType === AccessControlResourceType.ErrorTracking) {
return 'error tracking resource'
} else if (resourceType === AccessControlResourceType.ExternalDataSource) {
return 'data warehouse source'
} else if (resourceType === AccessControlResourceType.Metrics) {
return 'metrics resource'
} else if (resourceType === AccessControlResourceType.Tracing) {
return 'tracing resource'
} else if (resourceType === AccessControlResourceType.Workflow) {
return 'workflow'
} else if (resourceType === AccessControlResourceType.McpAnalytics) {
return 'MCP analytic'
} else if (resourceType === AccessControlResourceType.ReplayScanner) {
return 'replay vision resource'
} else if (resourceType === AccessControlResourceType.Stamphog) {
// Proper noun, so it stays capitalized inside "...permissions for this Stamphog resource."
return 'Stamphog resource'
}
return resourceType.replace(/_/g, ' ')
}
/**
* Checks if a user's current access level satisfies the required access level for a resource.
* Uses the ordered access levels to determine if the current level is sufficient.
*
* @param resourceType - The type of resource being accessed
* @param currentLevel - The user's current access level
* @param requiredLevel - The minimum required access level
* @returns True if the current level meets or exceeds the required level
*/
export const accessLevelSatisfied = (
resourceType: AccessControlResourceType,
currentLevel: AccessControlLevel,
requiredLevel: AccessControlLevel
): boolean => {
const levels = orderedAccessLevels(resourceType)
return levels.indexOf(currentLevel) >= levels.indexOf(requiredLevel)
}
/**
* Determines why access control is disabled for a user and resource.
* Checks if the user has sufficient permissions and returns a descriptive reason if not.
* Falls back to app context if user access level is not provided.
*
* @param resourceType - The type of resource being accessed
* @param minAccessLevel - The minimum required access level
* @param userAccessLevel - Optional user's current access level (falls back to app context)
* @param includeAccessDetails - Whether to include specific access level details in the reason
* @returns Descriptive reason for access denial, or null if access is granted
*/
export const getAccessControlDisabledReason = (
resourceType: AccessControlResourceType,
minAccessLevel: AccessControlLevel,
userAccessLevel?: AccessControlLevel,
includeAccessDetails: boolean = true
): string | null => {
// If the userAccessLevel is not provided, we use the app context for that resource type
const parsedUserAccessLevel = userAccessLevel ?? getAppContext()?.resource_access_control?.[resourceType]
// And if we can't figure out the user's access level from the arguments OR app context,
// we assume they don't have access to the resource to err on the side of caution
const hasAccess = parsedUserAccessLevel
? accessLevelSatisfied(resourceType, parsedUserAccessLevel, minAccessLevel)
: false
if (!hasAccess) {
let reason: string
if (resourceType === AccessControlResourceType.WarehouseObjects) {
// warehouse_objects is the umbrella scope id; the label users see in the picker is
// "Data warehouse tables & views". Use it verbatim here for clarity.
reason = `Requires ${toSentenceCase(minAccessLevel)} access to Data warehouse tables & views.`
} else {
reason = `You don't have sufficient permissions for this ${resourceTypeToString(resourceType)}.`
}
if (includeAccessDetails) {
reason += ` Your access level (${parsedUserAccessLevel ?? 'none'}) doesn't meet the required level (${minAccessLevel}).`
}
return reason
}
return null
}
/**
* Simple boolean check to determine if a user has access to a resource.
* Uses the access control disabled reason function and negates the result.
*
* @param resourceType - The type of resource being accessed
* @param minAccessLevel - The minimum required access level
* @param userAccessLevel - Optional user's current access level (falls back to app context)
* @returns True if the user has sufficient access, false otherwise
*/
export const userHasAccess = (
resourceType: AccessControlResourceType,
minAccessLevel: AccessControlLevel,
userAccessLevel?: AccessControlLevel
): boolean => {
return !getAccessControlDisabledReason(resourceType, minAccessLevel, userAccessLevel)
}
/** Entry/search-result types mapped to the resource type gating them - identity for types that
* are access control resources themselves, plus the backend's RESOURCE_INHERITANCE_MAP entries
* for types that appear in trees and search. */
const ENTRY_TYPE_TO_RESOURCE_TYPE: Record<string, AccessControlResourceType> = {
...Object.fromEntries(Object.values(AccessControlResourceType).map((value) => [value, value])),
session_recording_playlist: AccessControlResourceType.SessionRecording,
}
export const productHasEffectiveNoneAccess = (resourceType: AccessControlResourceType): boolean => {
return getAppContext()?.effective_resource_access_control?.[resourceType] === AccessControlLevel.None
}
/**
* Disabled reason for a product navigation item (sidebar product list, search product results)
* when the user's effective access to the product's resource is "none".
*
* Mirrors the scene gating in sceneLogic (which uses `effective_resource_access_control` and
* `sceneToAccessControlResourceType`), so items are disabled exactly when opening the target
* page would show "Access denied". Users with object-level grants get effective "viewer"
* access, so the product stays enabled for them.
*
* @param item - Navigation item with the scene key it points at (e.g. a FileSystemImport)
* @returns Reason to show on the disabled item, or undefined when the user has access
*/
export const getProductAccessDisabledReason = (item: {
sceneKey?: string
path?: string
displayLabel?: string
}): string | undefined => {
if (!item.sceneKey) {
return undefined
}
const resourceType = sceneToAccessControlResourceType[item.sceneKey as Scene]
const resources = Array.isArray(resourceType) ? resourceType : resourceType ? [resourceType] : []
if (!resources.length || !resources.every(productHasEffectiveNoneAccess)) {
return undefined
}
return `You don't have access to ${item.displayLabel || item.path || 'this product'}`
}
/**
* Disabled reason for an individual item (search result, Files/Starred entry).
*
* Uses the backend-resolved access level for the underlying object, which accounts for
* object-level overrides - an item the user was individually granted access to stays enabled
* even when they have "none" access to the product. Additionally checks the product's
* effective access: when it is "none" the scene gate denies every item of that type,
* including ones the user created (object creators keep object-level access but aren't
* reflected in the effective map), so those must be disabled too or clicking them would
* still land on "Access denied".
*
* @param entry - Entry carrying the backend-resolved `user_access_level` and its type
* @returns Reason to show on the disabled item, or undefined when the user has access
*/
export const getEntryAccessDisabledReason = (entry: {
user_access_level?: string | null
type?: string | null
}): string | undefined => {
const resourceType = entry.type ? ENTRY_TYPE_TO_RESOURCE_TYPE[entry.type] : undefined
const blockedByProduct = resourceType !== undefined && productHasEffectiveNoneAccess(resourceType)
if (!blockedByProduct && entry.user_access_level !== AccessControlLevel.None) {
return undefined
}
return `You don't have access to ${entry.type ? `this ${entry.type.replace(/_/g, ' ')}` : 'this item'}`
}
/**
* Returns a tooltip message for a resource type if it has special access control behavior.
* Use this to inform users about resource-specific access control limitations or clarifications.
*
* @param resource - The API scope object to get tooltip text for
* @returns Tooltip text describing special access control behavior, or null if no special behavior
*/
export const getAccessControlTooltip = (resource: APIScopeObject): string | null => {
if (resource === AccessControlResourceType.ExternalDataSource) {
return 'Access control only applies to managed sources (Stripe, Postgres, etc.) and covers CRUD operations on the source configuration. It does not restrict querying data from those sources.'
}
if (resource === AccessControlResourceType.WarehouseObjects) {
return 'Viewer is required to query a table or view via SQL. Editor and above also control creating, editing, and deleting tables, views (aka "models"), folders, and joins.'
}
if (resource === AccessControlResourceType.SharingConfiguration) {
return 'Controls whether users can share resources like dashboards, insights, etc. with anyone via a public link.'
}
if (resource === AccessControlResourceType.Metrics) {
return 'Controls access to the metrics product and its API. It does not restrict querying the underlying metrics tables with SQL.'
}
if (resource === AccessControlResourceType.LlmAnalytics) {
return 'Covers traces, datasets, provider keys, and the model picker.'
}
return null
}