recaptime.dev
@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@title Policies User Guide
2@group userguide
3
4Guide to using Policies.
5
6Overview
7========
8
9Policies are the objects used to control user's permissions to view, edit and
10interact with various objects.
11
12Policies can express complex rules, and each object may have its own custom
13policies.
14
15Capabilities and Policies
16=========================
17
18Each object type defines the various //Capabilities// users may have with
19regards to its instances; Most objects have "Visible To" and "Editable By"
20policies, and some have additional capabilities, such as "Can interact" for
21Phame posts and "Can Push" for Diffusion repositories.
22
23Each Application can also define Capabilities, such as "Can Create Objects", in
24addition to defining default values for new object's policies.
25
26A //Policy check// is applied for each capability of each object, against the
27acting user. For example, when a user tries to join a Project, the "Can Join"
28policy of the user is checked against the user to determine if they are allowed
29to perform the action.
30
31Object's pages will usually have a link to "Policy Details" in the tag list
32under the object's title.
33
34
35Policies and Rules
36==================
37
38Each Policy is made out of a list of Rules.
39
40
41A policy that has only one rule can be picked from the policy Selection
42dropdown, while more complex policies will be shown as "Custom Policy" and will
43show a dialog similar to this:
44
45
46```name=Custom Policy Editor
47
48Rules
49----------
50These 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
60There 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
76Extensions can write new Custom and Object rules - see "Writing Rules" below.
77
78
79=== Automatic Capabilities
80
81Some objects can allow some users to bypass some policy checks; For example, a
82user that has a task assigned to them can always view and edit the task, even
83if the policy would otherwise preclude them. The owner of a Revision can always
84view and edit the Revision.
85
86These policies are described under "{icon unlock-alt, color=red} Special Rules"
87in the "Policy Details" screen.
88
89=== File Attachments
90
91File objects can be //Attached// to other objects. Files attached to objects are
92visible to users who can view those objects. Files can be detached from objects
93in 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
116Objects 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
121will explain the current policies of the object; Use short name such as `T123`
122or PHID to specify an object.
123
124 $ bin/policy unlock --view <username> --edit <username> <object identifier>
125
126will modify the specified policy to allow the user to view/edit the object.
127Further editing can be done via the UI.
128
129== Extensions guide
130
131==== Writing Rules
132
133Extensions can provide additional Custom and Object rules for use on all
134objects and capabilities.
135
136To implement a Custom Rule, extend @{class:PhabricatorPolicyRule}. To implement
137an 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
152Example implementations:
153- Custom Rules:
154 - @{class:PhabricatorProjectsAllPolicyRule}
155 - @{class:PhabricatorLunarPhasePolicyRule}
156- Object Rules:
157 - @{class:ManiphestTaskAuthorPolicyRule}
158 - @{class:PhabricatorProjectMembersPolicyRule}
159
160==== Defining Capabilities
161
162Extensions can define Capabilities by implementing
163@{class:PhabricatorPolicyCapability}.
164
165Implementations are denoted by the string const `CAPABILITY`, and the
166implementation mostly consists of describing the capability.
167
168Objects can list their supported capabilities by implementing
169@{interface:PhabricatorPolicyInterface}. `getCapabilities` returns a list of
170capability constants that can be applied to the object.
171
172Objects that delegate their policies to other objects can implement
173@{interface:PhabricatorExtendedPolicyInterface}
174
175Example Implementations:
176- Capabilities: @{class:DiffusionPushCapability}
177- Policy Object: @{class:ConpherenceThread}
178- Extended Policy: @{class:DifferentialDiff}
179
180
181See Also
182========
183* @{article: Spaces User Guide}