@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
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
+183
+183
src/docs/user/userguide/policy.diviner
+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}