@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.) hq.recaptime.dev/wiki/Phorge
phorge phabricator
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

Diviner documentation for Policies

Summary: In prep for T15277, write some user docs about the existing Policies - how they work and how to use them.

Test Plan: look at it until blurry.

Reviewers: O1 Blessed Committers, valerio.bozzolan, aklapper

Reviewed By: O1 Blessed Committers, valerio.bozzolan, aklapper

Subscribers: aklapper, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno

Differential Revision: https://we.phorge.it/D26759

Aviv Eyal c5e33a50 4fb5bb52

+183
+183
src/docs/user/userguide/policy.diviner
··· 1 + @title Policies User Guide 2 + @group userguide 3 + 4 + Guide to using Policies. 5 + 6 + Overview 7 + ======== 8 + 9 + Policies are the objects used to control user's permissions to view, edit and 10 + interact with various objects. 11 + 12 + Policies can express complex rules, and each object may have its own custom 13 + policies. 14 + 15 + Capabilities and Policies 16 + ========================= 17 + 18 + Each object type defines the various //Capabilities// users may have with 19 + regards to its instances; Most objects have "Visible To" and "Editable By" 20 + policies, and some have additional capabilities, such as "Can interact" for 21 + Phame posts and "Can Push" for Diffusion repositories. 22 + 23 + Each Application can also define Capabilities, such as "Can Create Objects", in 24 + addition to defining default values for new object's policies. 25 + 26 + A //Policy check// is applied for each capability of each object, against the 27 + acting user. For example, when a user tries to join a Project, the "Can Join" 28 + policy of the user is checked against the user to determine if they are allowed 29 + to perform the action. 30 + 31 + Object's pages will usually have a link to "Policy Details" in the tag list 32 + under the object's title. 33 + 34 + 35 + Policies and Rules 36 + ================== 37 + 38 + Each Policy is made out of a list of Rules. 39 + 40 + 41 + A policy that has only one rule can be picked from the policy Selection 42 + dropdown, while more complex policies will be shown as "Custom Policy" and will 43 + show a dialog similar to this: 44 + 45 + 46 + ```name=Custom Policy Editor 47 + 48 + Rules 49 + ---------- 50 + These rules are processed in order. [New Rule] 51 + 52 + [Allow] [users ] [Named users ] [Remove] 53 + [Deny ] [members of any project] [Named projects ] [Remove] 54 + 55 + If No Rules Match [Deny ] all other users. 56 + 57 + ``` 58 + 59 + 60 + There are 3 types of rules: 61 + 62 + - **Global** rules are 4 special-case policies - "No one", "Admins", "All Users" 63 + and "Public (No Login Required)". These can be selected in the dropdown. 64 + "Public" is only available if the config `policy.allow-public` is enabled 65 + (default false). 66 + 67 + - **Object** rules are rules that are derived from the object being considered - 68 + for example, policies that apply to a Task can have "Task Author" as a rule, 69 + and policies that apply to project can have "members of project" rule. 70 + 71 + - **Custom** rules are all other rules, that only consider the actor (user), and 72 + not the object. 73 + Custom rules will usually accept some values to compare against the actor, 74 + such as Legalpad document or list of Projects. 75 + 76 + Extensions can write new Custom and Object rules - see "Writing Rules" below. 77 + 78 + 79 + === Automatic Capabilities 80 + 81 + Some objects can allow some users to bypass some policy checks; For example, a 82 + user that has a task assigned to them can always view and edit the task, even 83 + if the policy would otherwise preclude them. The owner of a Revision can always 84 + view and edit the Revision. 85 + 86 + These policies are described under "{icon unlock-alt, color=red} Special Rules" 87 + in the "Policy Details" screen. 88 + 89 + === File Attachments 90 + 91 + File objects can be //Attached// to other objects. Files attached to objects are 92 + visible to users who can view those objects. Files can be detached from objects 93 + in the File's "Details" view under "File Metadata". 94 + 95 + 96 + == Caveats 97 + 98 + 99 + * @{article@phorge: users|Administrators} cannot bypass policy checks. There 100 + are a few cases where a policy may be hard-coded to "admins", and several 101 + cases where "admins" is the default policy, but admins are subjects to the 102 + same policy checks as normal users. 103 + 104 + * Capabilities are very specific and only apply to their explicit description; 105 + For example, a Project's "Can Join" capability is not checked when user A is 106 + adding user B as a member; Instead, we check if user A is allowed to add 107 + members (which is just "Can Edit"). 108 + 109 + * The "Can Edit" capability generally allows the user to edit all policies on 110 + an object, including "Can Edit". 111 + 112 + 113 + == Field manuals 114 + ==== Lost Objects 115 + 116 + Objects that are not visible to anyone can be inspected and unlocked using the 117 + `bin/policy` script. 118 + 119 + $ bin/policy view <object identifier> 120 + 121 + will explain the current policies of the object; Use short name such as `T123` 122 + or PHID to specify an object. 123 + 124 + $ bin/policy unlock --view <username> --edit <username> <object identifier> 125 + 126 + will modify the specified policy to allow the user to view/edit the object. 127 + Further editing can be done via the UI. 128 + 129 + == Extensions guide 130 + 131 + ==== Writing Rules 132 + 133 + Extensions can provide additional Custom and Object rules for use on all 134 + objects and capabilities. 135 + 136 + To implement a Custom Rule, extend @{class:PhabricatorPolicyRule}. To implement 137 + an Object Rule, extend the same class and implement `getObjectPolicyKey`. 138 + 139 + - Methods `getRuleDescription` and `getValueForDisplay` 140 + are intended to describe the rule to users. 141 + - `getValueControlTemplate`, `getValueForStorage` allows providing values to 142 + Custom rules; Object rules can not accept values. 143 + - implement `getObjectPolicyKey`, `canApplyToObject`, `getObjectPolicyName`, 144 + `getObjectPolicyShortName`, etc. to define Object rules. 145 + - implement `willApplyRules` to pre-load any data that might be needed for 146 + evaluating the rule on any of the objects/values provided. 147 + - implement `applyRule` to evaluate the result of the rule for `$viewer` on 148 + `$object` with the `$value` provided. 149 + 150 + `applyRule` should return `true` to pass and `false` to block the action. 151 + 152 + Example implementations: 153 + - Custom Rules: 154 + - @{class:PhabricatorProjectsAllPolicyRule} 155 + - @{class:PhabricatorLunarPhasePolicyRule} 156 + - Object Rules: 157 + - @{class:ManiphestTaskAuthorPolicyRule} 158 + - @{class:PhabricatorProjectMembersPolicyRule} 159 + 160 + ==== Defining Capabilities 161 + 162 + Extensions can define Capabilities by implementing 163 + @{class:PhabricatorPolicyCapability}. 164 + 165 + Implementations are denoted by the string const `CAPABILITY`, and the 166 + implementation mostly consists of describing the capability. 167 + 168 + Objects can list their supported capabilities by implementing 169 + @{interface:PhabricatorPolicyInterface}. `getCapabilities` returns a list of 170 + capability constants that can be applied to the object. 171 + 172 + Objects that delegate their policies to other objects can implement 173 + @{interface:PhabricatorExtendedPolicyInterface} 174 + 175 + Example Implementations: 176 + - Capabilities: @{class:DiffusionPushCapability} 177 + - Policy Object: @{class:ConpherenceThread} 178 + - Extended Policy: @{class:DifferentialDiff} 179 + 180 + 181 + See Also 182 + ======== 183 + * @{article: Spaces User Guide}