Visibility — /rbac/visibility
Visibility rules answer the question "can this actor even discover that this resource exists?". They are independent from RBAC permission checks — a resource can be invisible to an actor who would otherwise be allowed to act on it, and visible to an actor RBAC will deny on every action.
The page is a per-resource lookup tool plus a manager for that resource's rules. You enter a resource identifier and type, hit Search, and the page loads visibilityRules(resourceIdentifier:, resourceType:, scopeId:) for that specific target.
What you see
Lookup form
Three inputs at the top:
- Resource identifier — the stable ID of the resource (e.g.
project-123) - Resource type — pick from the dropdown of registered resource types (sourced from
resourceTypes) - Search Rules button
Until you run a search the page shows only the "How Visibility Works" explainer card.
Results
Once Search runs you see:
- A header row with the count and the
type:identifierof the resource - An + Add Rule button (admins only)
- A list of rules, each showing the visibility type chip, priority, target reference (if any), active flag, and creation timestamp
Each rule row has a trash icon (admins only) for removal.
Rule types
The five built-in visibility types are color-coded:
| Type | Effect |
|---|---|
PUBLIC | Anyone in the workspace can see the resource |
PRIVATE | Only the owner can see it |
ROLE | Members of the targeted role can see it (target = role ID) |
GROUP | Members of the targeted group can see it (target = group ID) |
CUSTOM | Service-defined predicate (target type / target ID + metadata) |
Rules are evaluated in descending priority order, and the first rule whose condition matches the querying actor wins. So multiple rules can coexist on the same resource — the evaluator walks them top-down by priority and stops at the first match. A rule that doesn't match the actor (e.g. a ROLE rule when the actor isn't in that role) is skipped, and evaluation continues to the next rule. If no rule matches, the default visibility for the resource type applies.
This is what makes the combined-rule pattern in the tips below (a low-priority PRIVATE rule plus a higher-priority ROLE rule) work: the role rule is only "in effect" for actors who are in the role; everyone else falls through to the private rule.
Things you can do
| Task | How | Permission |
|---|---|---|
| Look up rules for a resource | Fill the form, Search Rules | canViewVisibility |
| Add a rule | + Add Rule → fill the dialog | canManageVisibility (visibility:write) |
| Remove a rule | Trash icon → confirm | canManageVisibility |
| Preview the resolved visibility for an actor | Use the checkVisibility mutation (API only; no UI today) | read access |
Adding a rule
The Add Rule form takes:
- Visibility type — one of
PUBLIC/PRIVATE/GROUP/ROLE/CUSTOM - Priority — integer; larger wins
- Target ID (optional) — required for
ROLE,GROUP, and mostCUSTOMrules; ignored forPUBLIC/PRIVATE - Target type (optional) — free-form label (e.g.
role,group,user)
Save. The new row is added immediately and emits the rbac.visibility.updated event.
Removing a rule
Tap the trash icon. A confirm dialog appears; on confirm the rule is removed (removeVisibilityRule) and the rules list refreshes. The dialog will not be reopenable; if you remove the wrong rule, re-create it.
Permissions you need
- The page is gated by
canViewVisibility(rbac:read). Workspace admins see everything; non-admin readers can browse but the + Add Rule and trash icons are hidden. - Mutating rules requires
canManageVisibility, backed byrbac:create/rbac:deleteand thevisibility:writeaction.
Tips
- The page does not list "all rules in the workspace" — there is no global enumeration in the contract. You must know the
resourceIdentifier+resourceTypeyou want to inspect. To find candidate resources, start on Resources. - Priority is not unique. If you create two rules with the same priority, the evaluator resolves the tie via creation order; prefer to make priorities distinct so the outcome is obvious from the UI.
- Visibility rules do not grant or deny actions — they only control discoverability. If an actor can see a resource but cannot act on it, that is RBAC working correctly; use the Permission Checker to confirm the action-level decision.
- A
PRIVATErule is owner-only; if you need "owner + a specific role", combine a low-priorityPRIVATErule with a higher-priorityROLErule pointing at that role.