Permissions Helper

Permissions Helper

Permissions Helper maps Forsetti actions and Jamf endpoints to required Jamf Pro privileges. It is designed to give administrators a readable permission matrix before they attempt an operation, and to help diagnose 403 API failures when a role is incomplete.

Architecture

flowchart TD
    Module["PermissionsMatrixModule"] --> Loader["PermissionsMatrixResourceLoader"]
    Module --> Verifier["PermissionsMatrixRuntimeVerifier"]
    Module --> VM["PermissionsMatrixViewModel"]
    Loader --> Resource["jamf_dashboard_permissions_matrix.v4.module_resource.json"]
    Resource --> Document["PermissionsMatrixDocument"]
    VM --> Views["PermissionsMatrixView"]
    Views --> Catalog["Privilege catalog"]
    Views --> EndpointCatalog["Endpoint catalog"]
    Views --> CommandExplorer["Command/action explorer"]
    Views --> Graph["Permission graph diagram"]
    Verifier --> Gateway["JamfAPIGateway"]
    Gateway --> Jamf["Jamf Pro auth/privilege endpoint"]
    VM --> Diagnostics["DiagnosticsReporting"]

Loading

User Workflow

sequenceDiagram
    participant User as Admin
    participant View as Permissions Helper
    participant Loader as Resource Loader
    participant VM as ViewModel
    participant Verifier as Runtime Verifier
    participant Jamf as Jamf Pro
    participant Diag as Diagnostics

    User->>View: open Permissions Helper
    View->>Loader: load bundled matrix
    Loader-->>View: actions, endpoints, privileges
    User->>View: search command or privilege
    View->>VM: filter actions
    VM-->>View: matching action cards
    User->>View: run token privilege check
    View->>Verifier: fetch current token privileges
    Verifier->>Jamf: authenticated auth/privilege request
    Jamf-->>Verifier: privilege list
    Verifier->>Diag: verification diagnostics
    Verifier-->>View: available/missing privilege state

Loading

Matrix Responsibilities

Responsibility	Detail
Action lookup	Operators can search by command/action display name.
Module filtering	Searches can be scoped to one module.
Privilege matching	Searches by privilege name surface actions requiring that privilege.
Requirement flattening	Heterogeneous requirement modes are flattened for display and testability.
Endpoint mapping	Actions can show API endpoint requirements.
Runtime verification	Current token privileges can be checked against expected privileges.
Visual explanation	Graph and matrix views show relationship between modules, commands, endpoints, and privileges.

Permission Graph

flowchart LR
    Module["Forsetti module"] --> Action["Action or command"]
    Action --> Endpoint["Jamf API endpoint"]
    Action --> HardReq["Hard-required privileges"]
    Action --> OptionalReq["Conditional or optional privileges"]
    Endpoint --> Gate["Endpoint gate privilege"]
    Gate --> Role["Jamf API role"]
    HardReq --> Role
    OptionalReq --> Role
    Role --> Token["Current token privileges"]

Loading

Support Technician Example

Support actions that queue MDM commands require both:

• An endpoint-level gate for viewing MDM command information through the Jamf Pro API.
• A per-command privilege, such as a restart, device information, erase, or mobile-device-specific command privilege.

flowchart TD
    Action["Support action: queue MDM command"] --> Gate["View MDM command information in Jamf Pro API"]
    Action --> CommandSpecific["Per-command privilege"]
    Gate --> TokenCheck["Token privilege check"]
    CommandSpecific --> TokenCheck
    TokenCheck -->|all present| Ready["Action ready"]
    TokenCheck -->|missing privilege| Blocked["Action blocked or degraded"]
    Blocked --> Guidance["Show missing privilege guidance"]

Loading

Important Files

Path	Role
ForsettiApp/Modules/PermissionsMatrix/PermissionsMatrixModule.swift	Composition root.
ForsettiApp/Modules/PermissionsMatrix/Resources/jamf_dashboard_permissions_matrix.v4.module_resource.json	Bundled offline matrix.
ForsettiApp/Modules/PermissionsMatrix/Services/PermissionsMatrixResourceLoader.swift	Resource loading and decoding.
ForsettiApp/Modules/PermissionsMatrix/Services/PermissionsMatrixRuntimeVerifier.swift	Runtime token privilege verification.
ForsettiApp/Modules/PermissionsMatrix/Models	Matrix, graph, hierarchy, and layout models.
ForsettiApp/Modules/PermissionsMatrix/Views	Matrix, catalog, command explorer, graph, and verification views.
ForsettiTests/PermissionsMatrixTests.swift	Matrix decode, search, flattening, and required-command tests.