<Button disabled={!canEdit}>Edit</Button>

How do we explain denied or unavailable actions without leaking sensitive information,
without lying to the user, and without turning the frontend into the source of authority?

type PermissionDecision = boolean;

type PermissionDecision = {
  allowed: boolean;
  code: PermissionDecisionCode;
  reason?: PermissionReason;
  recoverability: Recoverability;
  correlationId?: string;
};

- You are not logged in.
- Your session expired.
- You have the wrong role.
- You are in the wrong tenant.
- You are not assigned to this case.
- The case is closed.
- The feature is not enabled.
- The feature is temporarily degraded.
- The action requires MFA/step-up.
- The selected rows have mixed eligibility.
- The policy engine is unavailable.
- The app has not loaded permissions yet.

1. User confusion.
2. Support tickets.
3. Security workarounds.

{
  "allowed": false,
  "reason": "You can't do this because the case is closed"
}

{
  "allowed": false,
  "code": "RESOURCE_STATE_DENIED",
  "reason": {
    "type": "case_closed",
    "requiredState": ["open", "under_review"],
    "actualState": "closed"
  },
  "recoverability": "not_recoverable_by_user",
  "correlationId": "authz_01HX..."
}

type PermissionDecisionCode =
  | 'ALLOWED'
  | 'AUTHENTICATION_REQUIRED'
  | 'SESSION_EXPIRED'
  | 'TENANT_REQUIRED'
  | 'TENANT_MISMATCH'
  | 'PERMISSION_DENIED'
  | 'ROLE_REQUIRED'
  | 'SCOPE_DENIED'
  | 'OWNERSHIP_REQUIRED'
  | 'ASSIGNMENT_REQUIRED'
  | 'RESOURCE_NOT_FOUND_OR_NOT_ACCESSIBLE'
  | 'RESOURCE_STATE_DENIED'
  | 'FIELD_DENIED'
  | 'STEP_UP_REQUIRED'
  | 'SEPARATION_OF_DUTIES_DENIED'
  | 'FEATURE_NOT_ENABLED'
  | 'ENTITLEMENT_REQUIRED'
  | 'POLICY_UNAVAILABLE'
  | 'UNKNOWN';

type Recoverability =
  | 'login'
  | 'refresh_session'
  | 'switch_tenant'
  | 'request_access'
  | 'contact_admin'
  | 'upgrade_plan'
  | 'perform_step_up'
  | 'change_resource_state'
  | 'retry'
  | 'not_recoverable_by_user';

PERMISSION_DENIED -> request_access
PERMISSION_DENIED -> contact_admin
PERMISSION_DENIED -> not_recoverable_by_user

You cannot view Case 9281 because it belongs to the Financial Crime Unit.

You do not have access to this case.

404 Not Found

403 Forbidden

{
  "publicCode": "RESOURCE_NOT_FOUND_OR_NOT_ACCESSIBLE",
  "internalCode": "TENANT_MISMATCH",
  "correlationId": "authz_01HX..."
}

type PublicPermissionDecision = {
  allowed: boolean;
  publicCode: PublicPermissionCode;
  messageKey: string;
  recoverability: Recoverability;
  support?: {
    correlationId: string;
  };
};

type InternalPermissionDecision = PublicPermissionDecision & {
  internalCode: InternalPermissionCode;
  policyId: string;
  policyVersion: string;
  evaluatedInputs: RedactedPolicyInputs;
};

function toPublicDecision(internal: InternalPermissionDecision): PublicPermissionDecision {
  if (internal.internalCode === 'CASE_EXISTS_IN_OTHER_TENANT') {
    return {
      allowed: false,
      publicCode: 'RESOURCE_NOT_FOUND_OR_NOT_ACCESSIBLE',
      messageKey: 'access.notFoundOrNotAccessible',
      recoverability: 'not_recoverable_by_user',
      support: { correlationId: internal.support!.correlationId },
    };
  }

  return {
    allowed: internal.allowed,
    publicCode: internal.publicCode,
    messageKey: internal.messageKey,
    recoverability: internal.recoverability,
    support: internal.support,
  };
}

type AuthorizedButtonProps = {
  decision: PublicPermissionDecision;
  children: React.ReactNode;
  onClick: () => void;
};

function AuthorizedButton({ decision, children, onClick }: AuthorizedButtonProps) {
  if (decision.allowed) {
    return <button onClick={onClick}>{children}</button>;
  }

  if (decision.publicCode === 'FEATURE_NOT_ENABLED') {
    return null;
  }

  return (
    <button
      type="button"
      disabled
      aria-disabled="true"
      title={translate(decision.messageKey)}
    >
      {children}
    </button>
  );
}

function ActionWithReason({ decision, label, onClick }: {
  decision: PublicPermissionDecision;
  label: string;
  onClick: () => void;
}) {
  if (decision.allowed) {
    return <button onClick={onClick}>{label}</button>;
  }

  return (
    <div className="action-with-reason">
      <button disabled aria-disabled="true">
        {label}
      </button>
      <PermissionReason decision={decision} />
    </div>
  );
}

type RenderTreatment = 'hide' | 'disable' | 'explain' | 'prompt_step_up' | 'upgrade' | 'retry';

function treatmentFor(decision: PublicPermissionDecision): RenderTreatment {
  if (decision.allowed) return 'explain';

  switch (decision.recoverability) {
    case 'perform_step_up':
      return 'prompt_step_up';
    case 'request_access':
    case 'contact_admin':
    case 'change_resource_state':
      return 'explain';
    case 'upgrade_plan':
      return 'upgrade';
    case 'retry':
      return 'retry';
    case 'not_recoverable_by_user':
      return decision.publicCode === 'RESOURCE_NOT_FOUND_OR_NOT_ACCESSIBLE' ? 'hide' : 'disable';
    default:
      return 'disable';
  }
}

type AccessRequest = {
  id: string;
  requesterId: string;
  tenantId: string;
  action: string;
  resource: {
    type: string;
    id: string;
  };
  reasonCode: string;
  businessJustification: string;
  requestedDuration?: string;
  createdAt: string;
  status: 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
};

function PermissionReason({ decision }: { decision: PublicPermissionDecision }) {
  const message = translate(decision.messageKey);

  return (
    <div role="note" className="permission-reason">
      <span>{message}</span>
      <RecoveryAction decision={decision} />
      {decision.support?.correlationId && (
        <small>Reference: {decision.support.correlationId}</small>
      )}
    </div>
  );
}

function RecoveryAction({ decision }: { decision: PublicPermissionDecision }) {
  switch (decision.recoverability) {
    case 'request_access':
      return <RequestAccessButton decision={decision} />;
    case 'perform_step_up':
      return <StepUpButton decision={decision} />;
    case 'switch_tenant':
      return <SwitchTenantLink />;
    case 'retry':
      return <RetryPermissionCheckButton />;
    default:
      return null;
  }
}

Row action menu:
- disabled item
- short reason in tooltip
- optional "request access" action

- clear title
- safe explanation
- recovery action
- correlation ID
- link to help/access policy

{
  "allowed": false,
  "publicCode": "STEP_UP_REQUIRED",
  "messageKey": "access.stepUpRequired",
  "recoverability": "perform_step_up",
  "requiredAssuranceLevel": "aal2",
  "maxAgeSeconds": 300
}

function DeleteUserButton({ userId }: { userId: string }) {
  const decision = useCan({ action: 'user.delete', resourceType: 'user', resourceId: userId });

  if (decision.publicCode === 'STEP_UP_REQUIRED') {
    return (
      <button onClick={() => beginStepUp({ returnToAction: 'user.delete', resourceId: userId })}>
        Verify identity to delete user
      </button>
    );
  }

  return <AuthorizedButton decision={decision} onClick={() => deleteUser(userId)}>Delete user</AuthorizedButton>;
}

- 70 can be exported
- 20 are outside region scope
- 10 are closed

type BulkPermissionPreview = {
  action: string;
  total: number;
  allowedCount: number;
  deniedCount: number;
  groups: Array<{
    code: PermissionDecisionCode;
    count: number;
    messageKey: string;
  }>;
  mode: 'all_allowed' | 'partial_allowed' | 'none_allowed';
  operationPolicy: 'all_or_nothing' | 'allowed_subset';
};

Export selected cases
70 of 100 selected cases can be exported.
20 are outside your region. 10 are closed.

{
  "field": "sanctionRecommendation",
  "mode": "readonly",
  "reasonCode": "SEPARATION_OF_DUTIES_DENIED",
  "messageKey": "field.sodDenied"
}

function AuthorizedField({ field, permission, children }: {
  field: string;
  permission: FieldPermission;
  children: React.ReactNode;
}) {
  if (permission.mode === 'hidden') return null;

  return (
    <div>
      {cloneField(children, { readonly: permission.mode === 'readonly' })}
      {permission.reasonCode && <FieldPermissionHint permission={permission} />}
    </div>
  );
}

function AccessDeniedPage({ decision }: { decision: PublicPermissionDecision }) {
  return (
    <main className="access-denied">
      <h1>{titleFor(decision)}</h1>
      <p>{translate(decision.messageKey)}</p>
      <RecoveryAction decision={decision} />
      {decision.support?.correlationId && (
        <p className="reference">Reference: {decision.support.correlationId}</p>
      )}
    </main>
  );
}

Access denied.

You do not have access to this case.
Request access from your supervisor or contact support with reference AUTHZ-7K4F2.

This page is unavailable or you do not have access.

{
  "type": "https://example.com/problems/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "code": "PERMISSION_DENIED",
  "messageKey": "access.permissionDenied",
  "recoverability": "request_access",
  "correlationId": "authz_01HX..."
}

function decisionFromProblem(problem: AuthzProblem): PublicPermissionDecision {
  return {
    allowed: false,
    publicCode: problem.code,
    messageKey: problem.messageKey,
    recoverability: problem.recoverability,
    support: { correlationId: problem.correlationId },
  };
}

1. Do not reveal resource existence unless the user may know it exists.
2. Do not reveal sensitive ownership, assignment, region, or classification unless allowed.
3. Do not disclose internal role names if they reveal organization structure unnecessarily.
4. Do not expose raw policy names, SQL filters, tuple paths, or internal IDs.
5. Provide correlation IDs for support instead of internal details.
6. Make recovery clear when recovery is allowed.
7. Do not encourage users to ask random admins for broad access.
8. Prefer least-privilege request paths.

Only members of the Anti-Money Laundering Special Investigation Team can view this case.

You do not have access to this case. Request access if you need it for your work.

This case is unavailable or you do not have access.

Policy/resource service returns typed decision.
Session/permission projection carries public-safe decision.
React renders the decision.
Design system standardizes treatment.

React component guesses why user.role !== 'admin'.

{
  "event": "authorization.denied",
  "decisionId": "authz_01HX...",
  "subjectId": "user_123",
  "tenantId": "tenant_456",
  "action": "case.export",
  "resourceType": "case",
  "resourceId": "case_789",
  "publicCode": "PERMISSION_DENIED",
  "internalCode": "REGION_SCOPE_MISMATCH",
  "policyVersion": "2026-07-08.4",
  "requestId": "req_abc",
  "occurredAt": "2026-07-08T03:40:00Z"
}

Reference: AUTHZ-6G9Q2

{
  "messageKey": "access.case.requestAccess",
  "messageParams": {
    "resourceLabel": "case"
  }
}

translate(decision.messageKey, decision.messageParams)

describe('case export reason', () => {
  it('shows request access when user lacks export permission', () => {
    render(
      <ExportCaseButton
        decision={{
          allowed: false,
          publicCode: 'PERMISSION_DENIED',
          messageKey: 'access.permissionDenied',
          recoverability: 'request_access',
        }}
      />
    );

    expect(screen.getByRole('button', { name: /export/i })).toBeDisabled();
    expect(screen.getByText(/request access/i)).toBeInTheDocument();
  });

  it('does not reveal resource state when decision is not-found-or-not-accessible', () => {
    render(
      <AccessDeniedPage
        decision={{
          allowed: false,
          publicCode: 'RESOURCE_NOT_FOUND_OR_NOT_ACCESSIBLE',
          messageKey: 'access.notFoundOrNotAccessible',
          recoverability: 'not_recoverable_by_user',
        }}
      />
    );

    expect(screen.queryByText(/tenant mismatch/i)).not.toBeInTheDocument();
    expect(screen.queryByText(/financial crime unit/i)).not.toBeInTheDocument();
  });
});

- unauthenticated -> login CTA
- expired session -> re-login or refresh path
- tenant mismatch -> tenant switch or generic denial
- permission denied -> request access if allowed
- resource state denied -> state explanation
- step-up required -> MFA/passkey prompt
- policy unavailable -> retry/degraded state

- Do not rely only on tooltip hover for critical reason.
- Provide inline text or accessible description for important denial.
- Use aria-describedby to connect disabled action and reason when possible.
- Avoid focus traps in denied states.
- Ensure request-access actions are keyboard accessible.
- Avoid hiding controls that users need to discover for access request unless security requires hiding.

function DisabledActionWithReason({ id, label, reason }: {
  id: string;
  label: string;
  reason: string;
}) {
  const reasonId = `${id}-reason`;

  return (
    <div>
      <button disabled aria-describedby={reasonId}>
        {label}
      </button>
      <p id={reasonId}>{reason}</p>
    </div>
  );
}

Why can't I do this?
- Required action: case.export
- Your access: view only
- Resource state: closed
- What you can do: request export access or reopen case if permitted
- Reference: AUTHZ-6G9Q2

type PublicAccessExplanation = {
  titleKey: string;
  summaryKey: string;
  bullets: Array<{
    key: string;
    params?: Record<string, string>;
  }>;
  recovery?: PublicRecoveryAction;
  correlationId?: string;
};

Alice cannot export Case 123 because:
- Alice has role Investigator in Tenant A.
- Case 123 is assigned to Region B.
- Policy case.export requires region match or supervisor override.
- No active override grant exists.

{
  "rule": "case_export_region_scope",
  "subject.region": "north",
  "resource.region": "south",
  "result": "deny"
}

You do not have permission to export this case.

Denied because requester region does not match case region. Reference AUTHZ-6G9Q2.

Grant temporary cross-region export permission or reassign the case.

- Authenticate explanation endpoints.
- Rate limit sensitive explanation checks.
- Return generic messages for existence-sensitive resources.
- Redact internal reasons unless caller has admin/support permission.
- Log suspicious repeated denial probes.
- Do not let client submit arbitrary resource IDs for detailed explanation unless scoped.

app.post('/api/permissions/explain', async (req, res) => {
  const session = await requireSession(req);
  const request = parseExplainRequest(req.body);

  const decision = await policy.explainPublic(session.subject, request);

  // Public explanation is already redacted and existence-safe.
  res.json(decision.publicExplanation);
});

async function approveCase(caseId: string) {
  optimisticMarkApproved(caseId);

  try {
    await api.approveCase(caseId);
  } catch (error) {
    rollbackApproval(caseId);

    const problem = parseAuthzProblem(error);
    if (problem) {
      showPermissionToast(decisionFromProblem(problem));
      invalidatePermissionCache({ action: 'case.approve', resourceId: caseId });
      return;
    }

    throw error;
  }
}

User opens case page.
Permission says case.close allowed.
Supervisor closes the case in another tab.
User clicks close.
Server returns RESOURCE_STATE_DENIED.

1. Roll back optimistic changes.
2. Show safe reason.
3. Revalidate resource and permission projection.
4. Avoid retrying automatically if denial is deterministic.

Permission reason design
[ ] Does every denied sensitive action have a typed reason code?
[ ] Are internal reasons separated from public reasons?
[ ] Are messages safe against resource existence leaks?
[ ] Is recoverability explicit?
[ ] Can the UI render login, step-up, request access, tenant switch, retry, and generic denial differently?
[ ] Is there a correlation ID for support?
[ ] Are reasons localized via message keys?
[ ] Are field-level and bulk-action reasons supported?
[ ] Are denial reasons tested, not just visibility?
[ ] Are policy traces protected from regular users?
[ ] Does the server repeat authorization on submit?
[ ] Does stale denial invalidate relevant caches?

Can the user do this?

What is the safe, typed, recoverable explanation for the current access decision?

- truthful enough for the user
- safe enough for security
- structured enough for code
- stable enough for tests
- useful enough for support
- complete enough for audit