> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Permission Visibility Rollout

> Stage permission-driven UI visibility without weakening authorization.

## Security boundary

This rollout controls only whether internal users see navigation and global
actions that their effective permissions do not allow. Direct-route guards,
tRPC procedures, REST routes, service-layer tenant and entity checks, and
external collaborator containment remain permission enforced in every stage.

<Warning>
  Never use the visibility rollout state to authorize a read or write. A UI
  rollback intentionally restores legacy controls, which can still produce a
  server-side denial.
</Warning>

Case-scoped and external collaborators always receive enforced visibility.
Neither the platform stage nor an organization rollback can restore internal
navigation, tenant switchers, notifications, global actions, or search to those
principals.

## Controls

Set these values on every web node and restart or roll the nodes:

```bash theme={null}
# enforce (product default), canary, or observe
PERMISSION_VISIBILITY_ROLLOUT_STAGE=enforce

# Exact organization IDs; used only when the stage is canary
PERMISSION_VISIBILITY_CANARY_ORGANIZATION_IDS=org-pilot-1,org-pilot-2

# Emergency UI-only rollback exceptions in canary or enforce
PERMISSION_VISIBILITY_ROLLBACK_ORGANIZATION_IDS=
```

An unset stage defaults to `enforce`. An invalid explicit stage fails closed to
`enforce`. Empty or malformed list entries are ignored. The controls contain
organization IDs, so manage them as deployment configuration and do not expose
them to browser telemetry.

## Stages

1. **Broad enforcement (default):** Permission-driven hiding applies to every
   internal organization except an explicit UI rollback organization.
2. **Canary enforcement:** Set the stage to `canary` and list opted-in
   organization IDs. Permission-driven hiding applies only to those
   organizations. Other internal organizations remain in observation mode.
3. **Observe/audit:** Internal users retain legacy visibility. Permission route
   containment remains active. A visit to a visible but unauthorized route
   emits a `hidden_route_mismatch` signal and renders Access Denied.

Promote the same configuration to all web nodes. Mixed stages make telemetry
ambiguous and can cause navigation to change between requests.

## Telemetry and privacy

The authenticated, CSRF-protected telemetry endpoint re-resolves the principal
and rollout before recording a signal. It accepts only an event type and a
capability from the static manifest. It discards spoofed allowed-capability or
wrong-stage signals.

Monitor these OpenTelemetry counters and corresponding structured warning logs:

* `permission_visibility.hidden_route_mismatch`: an observation-stage control
  was visible but the permanent route guard denied it;
* `permission_visibility.authorization_denial`: an enforced or external
  principal reached a route that its permissions deny.

Labels are limited to rollout stage, enforcement state, rollout reason,
manifest capability, and internal/external principal class. User IDs,
organization IDs, route paths, entity IDs, query strings, tokens, and content
are not accepted or emitted.

## Promotion gates

Before each stage transition:

1. Run the authorization manifest, rollout, telemetry-route, external
   collaborator, and sensitive-entrypoint policy tests.
2. Verify a no-permission internal user can see a legacy control in `observe`
   but receives Access Denied and a server-side denial from direct API calls.
3. Verify a canary organization hides the same control while a non-canary
   organization does not.
4. Verify external collaborators see only the case-scoped shell in every stage.
5. Review mismatch and denial rates by capability. Investigate unexpected
   increases or a capability that has no expected authorized role.
6. Keep a stage through one deployment cycle, one permission-cache TTL, and one
   fresh-login cycle before expanding.

## UI-only rollback

For one organization, add its exact ID to
`PERMISSION_VISIBILITY_ROLLBACK_ORGANIZATION_IDS`. For a platform rollback, set
`PERMISSION_VISIBILITY_ROLLOUT_STAGE=observe`. Roll all web nodes and verify the
resolved `reason` label is `organization-rollback` or `platform-observe`.

Do not revert authorization middleware, permission requirements, tenant/entity
scope checks, route guards, or external collaborator restrictions. Do not
interpret restored controls as restored access. Remove the rollback exception
after the denial or role-template issue is understood and corrected.

## Operator follow-up

Operators must supply real canary organization IDs, configure collection and
alerts for the two counters, choose acceptable mismatch/denial thresholds,
record Security and Product approval for each promotion, and rehearse the
UI-only rollback in staging. Preserve rollout logs through the post-release
review window.