buster/api/prds/active/project_granular_asset_permissions.md

Project PRD: Granular Asset Permission Checks in Collections and Dashboards

Author: AI Assistant (Pair Programming with User) Date: 2023-10-27 Status: Proposed

1. Overview

This project aims to implement fine-grained permission checks for assets (like metrics and dashboards) contained within collections and dashboards. Currently, access checks primarily focus on the container, potentially exposing the existence of contained assets the user cannot access or hiding them inconsistently. This project will ensure that access to each contained asset is individually verified against the user's permissions, and the accessibility is clearly communicated in the API response.

2. Goals

• Implement fine-grained access control checks for individual assets (metrics, dashboards) listed within collections returned by get_collection_handler.
• Implement fine-grained access control checks for individual metrics listed within dashboards returned by get_dashboard_handler.
• Ensure users can see basic identifying information (ID, name, type) of assets within containers even if they lack CanView permission for those specific assets.
• Clearly indicate assets the user lacks permission to view using a has_access: bool flag in the response structures.
• Promote consistency by centralizing asset permission checking logic.

3. Non-Goals

• Changing the existing permission model (roles, identity types).
• Implementing access checks for asset types beyond metrics and dashboards initially.
• Modifying the frontend UI to visually represent the has_access status.
• Changing how permissions for the container (collection/dashboard itself) are checked.

4. Implementation Plan

The implementation is divided into the following phases and corresponding sub-PRDs. Phase 1 must be completed before Phases 2 and 3 can begin. Phases 2 and 3 can be implemented concurrently after Phase 1 is complete.

Phase 1: Foundational Permission Helper & Type Modifications (Blocking)

• Task: Implement the simplified permission checking helper and add has_access flags to relevant types.
• Sub-PRD: Refactor Sharing Permission Helper (Note: This PRD will be updated to reflect the simplified helper design).
• Also includes: Modifying BusterMetric and CollectionAsset types to add the has_access: bool field.
• Status: Upcoming
• Details: Create a helper primarily for contexts needing checks based only on ID, using cached org roles. Add the boolean flag to response types.

Phase 2: Concurrent Handler Enhancements (Requires Phase 1 Completion)

• Task A (Concurrent): Enhance Collection Handler
  • Sub-PRD: Enhance Collection Asset Permissions
  • Status: Upcoming
  • Details: Modify get_collection_handler to use efficient permission fetching (like fetch_..._with_permissions), check cached org roles, set has_access flag, and return minimal CollectionAsset if access denied.
• Task B (Concurrent): Enhance Dashboard/Metric Handlers
  • Sub-PRD: Enhance Dashboard Metric Permissions
  • Status: Upcoming
  • Details: Modify get_metric_handler (and get_dashboard_handler processing) to use efficient permission fetching, check cached org roles, set has_access flag, and return minimal BusterMetric if access denied. Downstream handlers like get_metric_data_handler will check this flag.

Phase 3: Integration Testing & Rollout

• Task: Perform end-to-end testing covering all enhanced handlers and scenarios involving mixed permissions.
• Details: Ensure collections, dashboards, and direct data execution requests correctly reflect and enforce the granular permissions.
• Rollout: Deploy changes once all phases are complete and tested.

5. High-Level Technical Design

• Introduce a has_access: bool field to CollectionAsset and BusterMetric response types.
• Develop a reusable helper function in libs/sharing primarily for pre-execution checks, using cached org roles and querying only direct asset_permissions.
• Modify get_collection_handler and get_metric_handler to efficiently fetch assets with their base permissions (handling deleted_at), then check cached org admin roles, and finally determine the has_access status.
• Ensure handlers return minimal, non-sensitive object representations when has_access is false.
• Ensure handlers like get_metric_data_handler check the has_access flag before proceeding with sensitive operations (like query execution).

6. Testing Strategy

• Each sub-PRD will define specific unit and integration tests.
• End-to-end tests should cover scenarios involving collections and dashboards containing a mix of accessible and inaccessible assets for a given user.

7. Rollout Plan

• Implement and merge sub-PRDs sequentially as defined in the Implementation Plan.
• Feature can be rolled out once all sub-PRDs are completed and merged. No feature flag is deemed necessary as this is primarily a backend enhancement improving correctness.

8. Dependencies

• Requires understanding of the existing permission system (asset_permissions, users_to_organizations).
• Modifies core handlers for collections and dashboards.

9. Open Questions/Decisions Made

• Public Container vs. Private Asset: Decided: Access to a public container does not grant implicit access to contained assets. The user's specific permissions for the contained asset will always be checked.
• Metadata for Inaccessible Assets: Decided: Assets marked has_access: false will include non-sensitive identifiers like id, name, and asset_type. Sensitive data (like metric content or dashboard config) will not be included.
• Error Handling for Permission Checks: Decided: If checking permission for a specific asset fails due to a database error (not lack of permission), that asset will be omitted from the results, and the error will be logged. Lack of permission results in has_access: false.