Effective Permissions API for policy visibility

[scotwells]

Summary

Users and operators need a way to understand what effective permissions a subject (user or group) has on a given resource. Today, answering "what can user X do on resource Y?" requires manually tracing through multiple PolicyBindings, Roles, inherited roles, and group memberships — or querying OpenFGA directly.

An Effective Permissions API would provide a single, computed view of a subject's resolved permissions on a resource, making access decisions transparent and debuggable.

Problem

• Users cannot easily discover what actions they're allowed to perform on a resource.
• Operators cannot quickly audit why a user has (or lacks) access without manually correlating PolicyBindings, Roles, and group memberships.
• Support teams spend time tracing permission chains when users report access issues.
• The authorization system's internals (OpenFGA tuples, hashed permission relations) are opaque to anyone outside the auth-provider.

Desired Outcome

A platform API that answers:

1. What can this subject do on this resource? — Returns the fully resolved set of permissions, accounting for direct bindings, group memberships, role inheritance, and resource hierarchy.
2. Why does this subject have this permission? — Returns the chain of PolicyBindings, Roles, and group memberships that grant a specific permission, enabling operators to audit and troubleshoot access.

Use Cases

• A user views their own permissions on an organization or project in the console.
• An operator audits what access a group has across resources before modifying a PolicyBinding.
• A support engineer investigates why a user can or cannot perform a specific action.
• A security review enumerates all subjects with write access to a sensitive resource.

Considerations

• The effective permissions are a computed projection — they should reflect the current resolved state of all contributing PolicyBindings, Roles, and group memberships.
• The API should support querying by subject (e.g., "all permissions for user X") and by resource (e.g., "all subjects with access to org Y").
• Performance matters — the computation involves role resolution, permission expansion, and potentially group membership traversal. Consider whether this is computed on-demand or materialized.
• This API could also serve as the foundation for simplifying how downstream systems (like the OpenFGA auth-provider) reconcile authorization state, by providing a single aggregated view instead of requiring each consumer to independently aggregate PolicyBindings.