ComponentsEnterpriseAccessGate

AccessGate

AccessGate adapts a capability surface to an application-owned permission decision without pretending UI controls are a security boundary.

Deny by defaultDisableHideReplaceEscalationLoading

Overview

Use AccessGate after policy resolution to make allowed and restricted capabilities predictable.

Billing export capability

Live preview

Switch roles and compare disabled, replaced, and hidden denied states.

Billing exportIncludes invoices, tax identifiers, and payment status
Finance Admin access requiredBilling exports contain sensitive invoice and tax data.
BillingExport.tsx
tsx
import { AccessGate, Button } from 'omverse-ui'
 
<AccessGate
allowed={permissions.canExportBilling}
deniedMode="disable"
title="Finance Admin access required"
reason="Request temporary access from the workspace owner."
action={<Button variant="outlined">Request access</Button>}
>
<Button>Export billing report</Button>
</AccessGate>

Anatomy

A restricted capability should identify the boundary, explain ownership, and provide a safe next step.

⌑Finance Admin access requiredBilling exports contain sensitive data.
Billing export
12345
  1. 1
    Policy result

    Consumes an already-resolved allowed or denied capability decision.

  2. 2
    Restricted explanation

    Names the required role, condition, or resource boundary.

  3. 3
    Escalation action

    Offers an access request, owner contact, or support path.

  4. 4
    Capability surface

    Renders normally, inert, replaced, or absent according to policy.

  5. 5
    State boundary

    Keeps restricted guidance programmatically associated and visible.

When to use

Use when the same capability must adapt consistently across roles, tenants, or resource conditions.

Recommended

  • Sensitive actions

    Adapt export, delete, billing, identity, and security capabilities.

  • Discoverable escalation

    Explain restrictions for features users commonly request.

  • Shared multi-role workspaces

    Apply one policy result consistently across repeated surfaces.

When not to use

AccessGate is presentation logic, not authorization or a substitute for simpler conditional rendering.

Avoid

  • Do not secure data with UI

    Authorize every read and mutation at the API or service boundary.

  • Do not hard-code role names

    Resolve granular capabilities in a policy layer before rendering.

  • Do not expose sensitive discovery

    Use hide mode when revealing that a capability exists creates risk.

Variants

Choose denied behavior from discoverability and security requirements, then choose a surface by available space.

Disable

Preserves the capability’s location while preventing interaction.

Hide

Removes the capability and all restricted messaging.

Replace

Swaps sensitive content for a dedicated restricted state.

Inline, panel, banner

Adapts guidance to actions, whole regions, and workflow notices.

States

Capability state should remain deterministic while roles and contextual policy data change.

StateTriggerVisual responseInteraction
LoadingPolicy is unresolvedProgress statusCapability remains unavailable
AllowedCapability grantedOriginal contentNative behavior remains unchanged
DisabledDenied but discoverableInert content and explanationOnly escalation remains available
HiddenDenied and undiscoverableNo rendered outputNo focus or announcement
ReplacedDenied region needs guidanceRestricted-state surfaceHelp or access request is available
ConditionalContext rule blocks accessReason names unmet conditionUser follows remediation path

Behavior

The component reflects policy; the application owns identity, resolution, refresh, authorization, and audit.

Fail closed

Omitted or unresolved allowed values deny access.

Refresh safely

Show loading while updated role and resource claims resolve.

Escalate intentionally

Request paths identify the capability and granting owner.

Enforce server-side

Repeat the same authorization before returning data or mutating state.

Accessibility

Restricted states must be perceivable, understandable, and absent from keyboard order when unavailable.

KeyAction
TabSkips inert denied content and reaches an escalation action when supplied.
EnterSpaceActivates the focused access-request or help control.
ShiftTabMoves backward without entering disabled descendants.
  • Use visible text in addition to lock icons and color.
  • Explain the required role or unmet condition.
  • Keep disabled descendants out of the focus order.
  • Do not announce intentionally hidden capabilities.
  • Use announceDenied only for a denied state that changes after user action.
  • Retain native semantics for allowed children.
  • Ensure request-access actions describe what will be requested.

Content guidelines

Permission messages should explain eligibility, ownership, and the next safe action without blaming the user.

Name the capability

Tell users exactly what is restricted.

ExampleBilling export access required

Name familiar roles

Use organization terminology users recognize.

ExampleAvailable to Finance Admins

Explain the boundary

State why the capability is controlled.

ExampleExports contain tax identifiers

Offer a next step

Identify who can grant access or how to request it.

ExampleRequest access from the workspace owner

Examples

Resolve granular capabilities outside the component and repeat authorization at the server boundary.

Restricted settings panel

Live preview

Replace an entire sensitive region with owner guidance.

Workspace settings are restrictedOnly Workspace Admins can change identity and security settings.
PolicyBoundAction.tsx
tsx
const capability = await policy.can({
actor: session.user,
action: 'billing.export',
resource: workspace,
})
 
<AccessGate
allowed={capability.allowed}
loading={capability.loading}
deniedMode={capability.discoverable ? 'disable' : 'hide'}
reason={capability.reason}
>
<ExportBillingAction />
</AccessGate>
 
// Always repeat authorization in the API handler.
await authorize(session.user, 'billing.export', workspace)

Props / API

AccessGate extends div attributes for allowed, loading, and denied capability states.

Props

PropTypeDefaultDescription
allowedbooleanfalseResolved application-owned capability result; omitted values deny by default.
childrenReactNoderequiredCapability surface shown when allowed or rendered inert in disable mode.
deniedMode'disable' | 'hide' | 'replace''disable'Presentation strategy when access is denied.
titleReactNode'Access restricted'Short restricted-state heading.
reasonReactNoderole guidancePlain-language explanation and ownership guidance.
actionReactNodeundefinedEscalation, help, or access-request control.
fallbackReactNodeundefinedFully custom content used in replace mode.
loadingbooleanfalseIndicates that the application is resolving capability data.
loadingLabelstring'Checking access'Status announced during capability resolution.
announceDeniedbooleanfalseAnnounces newly entered denied guidance as an alert.
variant'inline' | 'panel' | 'banner''inline'Controls restricted-state presentation.
size'sm' | 'md' | 'lg''md'Controls restricted-state type density.