pytest-authz-matrix 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pytest_authz_matrix-0.1.0/LICENSE +22 -0
- pytest_authz_matrix-0.1.0/PKG-INFO +331 -0
- pytest_authz_matrix-0.1.0/README.md +294 -0
- pytest_authz_matrix-0.1.0/pyproject.toml +76 -0
- pytest_authz_matrix-0.1.0/setup.cfg +4 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/__init__.py +7 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/case.py +173 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/config.py +241 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/discovery.py +154 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/exceptions.py +13 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/models.py +89 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/plugin.py +174 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/py.typed +1 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/reporting.py +144 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/templating.py +85 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/PKG-INFO +331 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/SOURCES.txt +23 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/dependency_links.txt +1 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/entry_points.txt +2 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/requires.txt +15 -0
- pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/top_level.txt +1 -0
- pytest_authz_matrix-0.1.0/tests/test_case.py +127 -0
- pytest_authz_matrix-0.1.0/tests/test_config.py +109 -0
- pytest_authz_matrix-0.1.0/tests/test_discovery.py +9 -0
- pytest_authz_matrix-0.1.0/tests/test_plugin.py +193 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aleshinloye Olamilekan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pytest-authz-matrix
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Authorization contract testing for Python web APIs
|
|
5
|
+
Author: Aleshinloye Olamilekan
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Leanstix/pytest-authz-matrix
|
|
8
|
+
Project-URL: Issues, https://github.com/Leanstix/pytest-authz-matrix/issues
|
|
9
|
+
Project-URL: Repository, https://github.com/Leanstix/pytest-authz-matrix
|
|
10
|
+
Keywords: pytest,authorization,django,drf,security,multi-tenant
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Framework :: Pytest
|
|
13
|
+
Classifier: Framework :: Django
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Software Development :: Testing
|
|
19
|
+
Classifier: Topic :: Security
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: pytest>=7.4
|
|
24
|
+
Requires-Dist: PyYAML>=6.0
|
|
25
|
+
Provides-Extra: django
|
|
26
|
+
Requires-Dist: Django>=4.2; extra == "django"
|
|
27
|
+
Requires-Dist: djangorestframework>=3.14; extra == "django"
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: build>=1.2; extra == "dev"
|
|
30
|
+
Requires-Dist: Django>=4.2; extra == "dev"
|
|
31
|
+
Requires-Dist: djangorestframework>=3.14; extra == "dev"
|
|
32
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
33
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
34
|
+
Requires-Dist: ruff>=0.5; extra == "dev"
|
|
35
|
+
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
# pytest-authz-matrix
|
|
39
|
+
|
|
40
|
+
[](https://github.com/Leanstix/pytest-authz-matrix/actions/workflows/ci.yml)
|
|
41
|
+
[](https://www.python.org/)
|
|
42
|
+
[](LICENSE)
|
|
43
|
+
|
|
44
|
+
Authorization contract testing for Python web APIs.
|
|
45
|
+
|
|
46
|
+
`pytest-authz-matrix` expands one pytest test into the complete actor × resource-relationship
|
|
47
|
+
matrix for an endpoint. For Django REST Framework projects, it can also inventory API routes
|
|
48
|
+
and report which HTTP method/route pairs do not have an authorization contract.
|
|
49
|
+
|
|
50
|
+
It is built for the bugs that ordinary authentication tests miss:
|
|
51
|
+
|
|
52
|
+
- a user retrieves another user's object by changing an ID;
|
|
53
|
+
- a tenant administrator reaches an object belonging to another tenant;
|
|
54
|
+
- a list endpoint leaks foreign rows while its detail endpoint is protected;
|
|
55
|
+
- an endpoint returns `403` when policy requires concealing the object's existence with `404`;
|
|
56
|
+
- a new DRF route ships without any ownership or cross-tenant test.
|
|
57
|
+
|
|
58
|
+
> **Status:** `0.1.0` is an alpha focused on explicit DRF authorization contracts. The plugin
|
|
59
|
+
> discovers untested routes; it deliberately does not guess your business authorization policy.
|
|
60
|
+
|
|
61
|
+
## Quick start
|
|
62
|
+
|
|
63
|
+
Install the plugin with its DRF integration:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pip install "pytest-authz-matrix[django]"
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Create `authz-matrix.yml` in the pytest root:
|
|
70
|
+
|
|
71
|
+
```yaml
|
|
72
|
+
version: 1
|
|
73
|
+
|
|
74
|
+
actors:
|
|
75
|
+
owner: owner_client
|
|
76
|
+
same_tenant_user: same_tenant_client
|
|
77
|
+
foreign_tenant_user: foreign_tenant_client
|
|
78
|
+
anonymous: anonymous_client
|
|
79
|
+
|
|
80
|
+
resources:
|
|
81
|
+
booking:
|
|
82
|
+
fixture: booking_matrix
|
|
83
|
+
lookup: pk
|
|
84
|
+
|
|
85
|
+
contracts:
|
|
86
|
+
booking.retrieve:
|
|
87
|
+
method: GET
|
|
88
|
+
path: /api/bookings/{resource}/
|
|
89
|
+
route_name: booking-detail
|
|
90
|
+
resource: booking
|
|
91
|
+
matrix:
|
|
92
|
+
owner:
|
|
93
|
+
owned: allow
|
|
94
|
+
same_tenant: conceal
|
|
95
|
+
foreign_tenant: conceal
|
|
96
|
+
same_tenant_user:
|
|
97
|
+
owned: conceal
|
|
98
|
+
same_tenant: allow
|
|
99
|
+
foreign_tenant: conceal
|
|
100
|
+
foreign_tenant_user:
|
|
101
|
+
owned: conceal
|
|
102
|
+
same_tenant: conceal
|
|
103
|
+
foreign_tenant: allow
|
|
104
|
+
anonymous:
|
|
105
|
+
owned: unauthenticated
|
|
106
|
+
same_tenant: unauthenticated
|
|
107
|
+
foreign_tenant: unauthenticated
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The actor fixtures return the API clients that already know how your project authenticates:
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
import pytest
|
|
114
|
+
from rest_framework.test import APIClient
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
@pytest.fixture
|
|
118
|
+
def owner_client(owner):
|
|
119
|
+
client = APIClient()
|
|
120
|
+
client.force_authenticate(owner)
|
|
121
|
+
return client
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@pytest.fixture
|
|
125
|
+
def same_tenant_client(same_tenant_user):
|
|
126
|
+
client = APIClient()
|
|
127
|
+
client.force_authenticate(same_tenant_user)
|
|
128
|
+
return client
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
@pytest.fixture
|
|
132
|
+
def foreign_tenant_client(foreign_tenant_user):
|
|
133
|
+
client = APIClient()
|
|
134
|
+
client.force_authenticate(foreign_tenant_user)
|
|
135
|
+
return client
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
@pytest.fixture
|
|
139
|
+
def anonymous_client():
|
|
140
|
+
return APIClient()
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
The resource fixture maps the relationship names in YAML to real model instances:
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
@pytest.fixture
|
|
147
|
+
def booking_matrix(owner_booking, same_tenant_booking, foreign_tenant_booking):
|
|
148
|
+
return {
|
|
149
|
+
"owned": owner_booking,
|
|
150
|
+
"same_tenant": same_tenant_booking,
|
|
151
|
+
"foreign_tenant": foreign_tenant_booking,
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Finally, bind a test to the contract:
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
import pytest
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
@pytest.mark.authz_contract("booking.retrieve")
|
|
162
|
+
def test_booking_retrieve_authorization(authz_case):
|
|
163
|
+
authz_case.run()
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
That single function becomes 12 independent pytest cases with readable IDs such as:
|
|
167
|
+
|
|
168
|
+
```text
|
|
169
|
+
booking.retrieve[owner-owned-allow]
|
|
170
|
+
booking.retrieve[owner-foreign_tenant-conceal]
|
|
171
|
+
booking.retrieve[anonymous-owned-unauthenticated]
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Outcomes
|
|
175
|
+
|
|
176
|
+
The built-in outcomes are HTTP status contracts:
|
|
177
|
+
|
|
178
|
+
| Outcome | Default status | Meaning |
|
|
179
|
+
|---|---:|---|
|
|
180
|
+
| `allow` | `200` | The actor may perform the operation. |
|
|
181
|
+
| `deny` | `403` | The actor is authenticated but forbidden. |
|
|
182
|
+
| `conceal` | `404` | The resource's existence must not be disclosed. |
|
|
183
|
+
| `unauthenticated` | `401` | Authentication is required. |
|
|
184
|
+
|
|
185
|
+
Override defaults globally when an endpoint legitimately returns another success status:
|
|
186
|
+
|
|
187
|
+
```yaml
|
|
188
|
+
outcomes:
|
|
189
|
+
allow: [200, 201, 204]
|
|
190
|
+
deny: [403]
|
|
191
|
+
conceal: [404]
|
|
192
|
+
unauthenticated: [401]
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Or override one matrix cell:
|
|
196
|
+
|
|
197
|
+
```yaml
|
|
198
|
+
matrix:
|
|
199
|
+
owner:
|
|
200
|
+
owned:
|
|
201
|
+
outcome: allow
|
|
202
|
+
statuses: [200, 204]
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
An integer or list is also accepted for a status-only expectation:
|
|
206
|
+
|
|
207
|
+
```yaml
|
|
208
|
+
matrix:
|
|
209
|
+
owner:
|
|
210
|
+
owned: [200, 206]
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## Mutating endpoints
|
|
214
|
+
|
|
215
|
+
Request bodies and query strings can come from fixtures:
|
|
216
|
+
|
|
217
|
+
```yaml
|
|
218
|
+
contracts:
|
|
219
|
+
booking.update:
|
|
220
|
+
method: PATCH
|
|
221
|
+
path: /api/bookings/{resource}/
|
|
222
|
+
route_name: booking-detail
|
|
223
|
+
resource: booking
|
|
224
|
+
request:
|
|
225
|
+
data_fixture: booking_update_payload
|
|
226
|
+
query_fixture: update_query
|
|
227
|
+
format: json
|
|
228
|
+
headers:
|
|
229
|
+
X-Test-Source: authz-matrix
|
|
230
|
+
matrix:
|
|
231
|
+
owner:
|
|
232
|
+
owned: allow
|
|
233
|
+
foreign_tenant: conceal
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
For state or side-effect assertions, split execution from the status assertion:
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
@pytest.mark.authz_contract("booking.update")
|
|
240
|
+
def test_booking_update_authorization(authz_case):
|
|
241
|
+
original_status = authz_case.resource.status
|
|
242
|
+
|
|
243
|
+
response = authz_case.execute()
|
|
244
|
+
|
|
245
|
+
authz_case.resource.refresh_from_db()
|
|
246
|
+
if authz_case.outcome != "allow":
|
|
247
|
+
assert authz_case.resource.status == original_status
|
|
248
|
+
authz_case.assert_response(response)
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
`authz_case.execute()` also accepts per-test `data`, `query`, and `headers` overrides.
|
|
252
|
+
|
|
253
|
+
## Route coverage
|
|
254
|
+
|
|
255
|
+
Add `route_name` to contracts whenever possible. The plugin matches the contract's HTTP method
|
|
256
|
+
and Django URL name against DRF's URL resolver. Without a route name, it falls back to normalized
|
|
257
|
+
path matching.
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
pytest --authz-report
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Example output:
|
|
264
|
+
|
|
265
|
+
```text
|
|
266
|
+
============================= authorization matrix =============================
|
|
267
|
+
authorization cases: 12/12 asserted, 12 passed, 0 failed
|
|
268
|
+
authorization contracts: 1/1 exercised
|
|
269
|
+
DRF route coverage: 9/11 (81.8%)
|
|
270
|
+
missing: PATCH children-detail
|
|
271
|
+
missing: POST booking-refund
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Fail CI when route coverage drops below a threshold:
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
pytest --authz-report --authz-fail-under=85
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
Write machine-readable results:
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
pytest --authz-report-json=build/authz-report.json
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Discovery is best-effort and only runs when Django is configured in the pytest session. A plain
|
|
287
|
+
Python or non-Django test suite can still use explicit matrices with any client fixture exposing
|
|
288
|
+
HTTP method functions such as `.get()` or `.patch()`.
|
|
289
|
+
|
|
290
|
+
## Path templates
|
|
291
|
+
|
|
292
|
+
Given a resource fixture object, the following placeholders are available:
|
|
293
|
+
|
|
294
|
+
| Placeholder | Resolution |
|
|
295
|
+
|---|---|
|
|
296
|
+
| `{resource}` | The resource field configured by `lookup` (`pk` by default). |
|
|
297
|
+
| `{resource.uuid}` | Any mapping key or object attribute on the selected resource. |
|
|
298
|
+
| `{params.estate}` | A static value from the contract's `params` mapping. |
|
|
299
|
+
|
|
300
|
+
Values are URL-encoded before insertion. See [the full configuration reference](docs/configuration.md)
|
|
301
|
+
for endpoint-only contracts, request options, and validation rules.
|
|
302
|
+
|
|
303
|
+
## What this version does not do
|
|
304
|
+
|
|
305
|
+
- It does not infer who should own an object. Fixtures define that truth explicitly.
|
|
306
|
+
- It does not prove that response bodies contain no foreign objects; add a list-response assertion.
|
|
307
|
+
- It does not intercept emails, Celery tasks, or external API calls automatically.
|
|
308
|
+
- It does not yet generate contracts from OpenAPI or support a first-class FastAPI adapter.
|
|
309
|
+
- It does not replace database row-level-security tests or a security review.
|
|
310
|
+
|
|
311
|
+
These boundaries are intentional. The first release makes authorization policy executable and
|
|
312
|
+
shows what remains untested without claiming to solve authorization automatically.
|
|
313
|
+
|
|
314
|
+
## Development
|
|
315
|
+
|
|
316
|
+
```bash
|
|
317
|
+
python -m venv .venv
|
|
318
|
+
. .venv/bin/activate
|
|
319
|
+
pip install -e ".[dev]"
|
|
320
|
+
pytest
|
|
321
|
+
ruff check src tests
|
|
322
|
+
mypy src
|
|
323
|
+
python -m build
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. The architecture and planned
|
|
327
|
+
extension points are documented in [docs/design.md](docs/design.md).
|
|
328
|
+
|
|
329
|
+
## License
|
|
330
|
+
|
|
331
|
+
MIT
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# pytest-authz-matrix
|
|
2
|
+
|
|
3
|
+
[](https://github.com/Leanstix/pytest-authz-matrix/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.python.org/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
Authorization contract testing for Python web APIs.
|
|
8
|
+
|
|
9
|
+
`pytest-authz-matrix` expands one pytest test into the complete actor × resource-relationship
|
|
10
|
+
matrix for an endpoint. For Django REST Framework projects, it can also inventory API routes
|
|
11
|
+
and report which HTTP method/route pairs do not have an authorization contract.
|
|
12
|
+
|
|
13
|
+
It is built for the bugs that ordinary authentication tests miss:
|
|
14
|
+
|
|
15
|
+
- a user retrieves another user's object by changing an ID;
|
|
16
|
+
- a tenant administrator reaches an object belonging to another tenant;
|
|
17
|
+
- a list endpoint leaks foreign rows while its detail endpoint is protected;
|
|
18
|
+
- an endpoint returns `403` when policy requires concealing the object's existence with `404`;
|
|
19
|
+
- a new DRF route ships without any ownership or cross-tenant test.
|
|
20
|
+
|
|
21
|
+
> **Status:** `0.1.0` is an alpha focused on explicit DRF authorization contracts. The plugin
|
|
22
|
+
> discovers untested routes; it deliberately does not guess your business authorization policy.
|
|
23
|
+
|
|
24
|
+
## Quick start
|
|
25
|
+
|
|
26
|
+
Install the plugin with its DRF integration:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pip install "pytest-authz-matrix[django]"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Create `authz-matrix.yml` in the pytest root:
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
version: 1
|
|
36
|
+
|
|
37
|
+
actors:
|
|
38
|
+
owner: owner_client
|
|
39
|
+
same_tenant_user: same_tenant_client
|
|
40
|
+
foreign_tenant_user: foreign_tenant_client
|
|
41
|
+
anonymous: anonymous_client
|
|
42
|
+
|
|
43
|
+
resources:
|
|
44
|
+
booking:
|
|
45
|
+
fixture: booking_matrix
|
|
46
|
+
lookup: pk
|
|
47
|
+
|
|
48
|
+
contracts:
|
|
49
|
+
booking.retrieve:
|
|
50
|
+
method: GET
|
|
51
|
+
path: /api/bookings/{resource}/
|
|
52
|
+
route_name: booking-detail
|
|
53
|
+
resource: booking
|
|
54
|
+
matrix:
|
|
55
|
+
owner:
|
|
56
|
+
owned: allow
|
|
57
|
+
same_tenant: conceal
|
|
58
|
+
foreign_tenant: conceal
|
|
59
|
+
same_tenant_user:
|
|
60
|
+
owned: conceal
|
|
61
|
+
same_tenant: allow
|
|
62
|
+
foreign_tenant: conceal
|
|
63
|
+
foreign_tenant_user:
|
|
64
|
+
owned: conceal
|
|
65
|
+
same_tenant: conceal
|
|
66
|
+
foreign_tenant: allow
|
|
67
|
+
anonymous:
|
|
68
|
+
owned: unauthenticated
|
|
69
|
+
same_tenant: unauthenticated
|
|
70
|
+
foreign_tenant: unauthenticated
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The actor fixtures return the API clients that already know how your project authenticates:
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
import pytest
|
|
77
|
+
from rest_framework.test import APIClient
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@pytest.fixture
|
|
81
|
+
def owner_client(owner):
|
|
82
|
+
client = APIClient()
|
|
83
|
+
client.force_authenticate(owner)
|
|
84
|
+
return client
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@pytest.fixture
|
|
88
|
+
def same_tenant_client(same_tenant_user):
|
|
89
|
+
client = APIClient()
|
|
90
|
+
client.force_authenticate(same_tenant_user)
|
|
91
|
+
return client
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@pytest.fixture
|
|
95
|
+
def foreign_tenant_client(foreign_tenant_user):
|
|
96
|
+
client = APIClient()
|
|
97
|
+
client.force_authenticate(foreign_tenant_user)
|
|
98
|
+
return client
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
@pytest.fixture
|
|
102
|
+
def anonymous_client():
|
|
103
|
+
return APIClient()
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The resource fixture maps the relationship names in YAML to real model instances:
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
@pytest.fixture
|
|
110
|
+
def booking_matrix(owner_booking, same_tenant_booking, foreign_tenant_booking):
|
|
111
|
+
return {
|
|
112
|
+
"owned": owner_booking,
|
|
113
|
+
"same_tenant": same_tenant_booking,
|
|
114
|
+
"foreign_tenant": foreign_tenant_booking,
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Finally, bind a test to the contract:
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
import pytest
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@pytest.mark.authz_contract("booking.retrieve")
|
|
125
|
+
def test_booking_retrieve_authorization(authz_case):
|
|
126
|
+
authz_case.run()
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
That single function becomes 12 independent pytest cases with readable IDs such as:
|
|
130
|
+
|
|
131
|
+
```text
|
|
132
|
+
booking.retrieve[owner-owned-allow]
|
|
133
|
+
booking.retrieve[owner-foreign_tenant-conceal]
|
|
134
|
+
booking.retrieve[anonymous-owned-unauthenticated]
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Outcomes
|
|
138
|
+
|
|
139
|
+
The built-in outcomes are HTTP status contracts:
|
|
140
|
+
|
|
141
|
+
| Outcome | Default status | Meaning |
|
|
142
|
+
|---|---:|---|
|
|
143
|
+
| `allow` | `200` | The actor may perform the operation. |
|
|
144
|
+
| `deny` | `403` | The actor is authenticated but forbidden. |
|
|
145
|
+
| `conceal` | `404` | The resource's existence must not be disclosed. |
|
|
146
|
+
| `unauthenticated` | `401` | Authentication is required. |
|
|
147
|
+
|
|
148
|
+
Override defaults globally when an endpoint legitimately returns another success status:
|
|
149
|
+
|
|
150
|
+
```yaml
|
|
151
|
+
outcomes:
|
|
152
|
+
allow: [200, 201, 204]
|
|
153
|
+
deny: [403]
|
|
154
|
+
conceal: [404]
|
|
155
|
+
unauthenticated: [401]
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Or override one matrix cell:
|
|
159
|
+
|
|
160
|
+
```yaml
|
|
161
|
+
matrix:
|
|
162
|
+
owner:
|
|
163
|
+
owned:
|
|
164
|
+
outcome: allow
|
|
165
|
+
statuses: [200, 204]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
An integer or list is also accepted for a status-only expectation:
|
|
169
|
+
|
|
170
|
+
```yaml
|
|
171
|
+
matrix:
|
|
172
|
+
owner:
|
|
173
|
+
owned: [200, 206]
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Mutating endpoints
|
|
177
|
+
|
|
178
|
+
Request bodies and query strings can come from fixtures:
|
|
179
|
+
|
|
180
|
+
```yaml
|
|
181
|
+
contracts:
|
|
182
|
+
booking.update:
|
|
183
|
+
method: PATCH
|
|
184
|
+
path: /api/bookings/{resource}/
|
|
185
|
+
route_name: booking-detail
|
|
186
|
+
resource: booking
|
|
187
|
+
request:
|
|
188
|
+
data_fixture: booking_update_payload
|
|
189
|
+
query_fixture: update_query
|
|
190
|
+
format: json
|
|
191
|
+
headers:
|
|
192
|
+
X-Test-Source: authz-matrix
|
|
193
|
+
matrix:
|
|
194
|
+
owner:
|
|
195
|
+
owned: allow
|
|
196
|
+
foreign_tenant: conceal
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
For state or side-effect assertions, split execution from the status assertion:
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
@pytest.mark.authz_contract("booking.update")
|
|
203
|
+
def test_booking_update_authorization(authz_case):
|
|
204
|
+
original_status = authz_case.resource.status
|
|
205
|
+
|
|
206
|
+
response = authz_case.execute()
|
|
207
|
+
|
|
208
|
+
authz_case.resource.refresh_from_db()
|
|
209
|
+
if authz_case.outcome != "allow":
|
|
210
|
+
assert authz_case.resource.status == original_status
|
|
211
|
+
authz_case.assert_response(response)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`authz_case.execute()` also accepts per-test `data`, `query`, and `headers` overrides.
|
|
215
|
+
|
|
216
|
+
## Route coverage
|
|
217
|
+
|
|
218
|
+
Add `route_name` to contracts whenever possible. The plugin matches the contract's HTTP method
|
|
219
|
+
and Django URL name against DRF's URL resolver. Without a route name, it falls back to normalized
|
|
220
|
+
path matching.
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
pytest --authz-report
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Example output:
|
|
227
|
+
|
|
228
|
+
```text
|
|
229
|
+
============================= authorization matrix =============================
|
|
230
|
+
authorization cases: 12/12 asserted, 12 passed, 0 failed
|
|
231
|
+
authorization contracts: 1/1 exercised
|
|
232
|
+
DRF route coverage: 9/11 (81.8%)
|
|
233
|
+
missing: PATCH children-detail
|
|
234
|
+
missing: POST booking-refund
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Fail CI when route coverage drops below a threshold:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
pytest --authz-report --authz-fail-under=85
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Write machine-readable results:
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
pytest --authz-report-json=build/authz-report.json
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Discovery is best-effort and only runs when Django is configured in the pytest session. A plain
|
|
250
|
+
Python or non-Django test suite can still use explicit matrices with any client fixture exposing
|
|
251
|
+
HTTP method functions such as `.get()` or `.patch()`.
|
|
252
|
+
|
|
253
|
+
## Path templates
|
|
254
|
+
|
|
255
|
+
Given a resource fixture object, the following placeholders are available:
|
|
256
|
+
|
|
257
|
+
| Placeholder | Resolution |
|
|
258
|
+
|---|---|
|
|
259
|
+
| `{resource}` | The resource field configured by `lookup` (`pk` by default). |
|
|
260
|
+
| `{resource.uuid}` | Any mapping key or object attribute on the selected resource. |
|
|
261
|
+
| `{params.estate}` | A static value from the contract's `params` mapping. |
|
|
262
|
+
|
|
263
|
+
Values are URL-encoded before insertion. See [the full configuration reference](docs/configuration.md)
|
|
264
|
+
for endpoint-only contracts, request options, and validation rules.
|
|
265
|
+
|
|
266
|
+
## What this version does not do
|
|
267
|
+
|
|
268
|
+
- It does not infer who should own an object. Fixtures define that truth explicitly.
|
|
269
|
+
- It does not prove that response bodies contain no foreign objects; add a list-response assertion.
|
|
270
|
+
- It does not intercept emails, Celery tasks, or external API calls automatically.
|
|
271
|
+
- It does not yet generate contracts from OpenAPI or support a first-class FastAPI adapter.
|
|
272
|
+
- It does not replace database row-level-security tests or a security review.
|
|
273
|
+
|
|
274
|
+
These boundaries are intentional. The first release makes authorization policy executable and
|
|
275
|
+
shows what remains untested without claiming to solve authorization automatically.
|
|
276
|
+
|
|
277
|
+
## Development
|
|
278
|
+
|
|
279
|
+
```bash
|
|
280
|
+
python -m venv .venv
|
|
281
|
+
. .venv/bin/activate
|
|
282
|
+
pip install -e ".[dev]"
|
|
283
|
+
pytest
|
|
284
|
+
ruff check src tests
|
|
285
|
+
mypy src
|
|
286
|
+
python -m build
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. The architecture and planned
|
|
290
|
+
extension points are documented in [docs/design.md](docs/design.md).
|
|
291
|
+
|
|
292
|
+
## License
|
|
293
|
+
|
|
294
|
+
MIT
|