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.
Files changed (25) hide show
  1. pytest_authz_matrix-0.1.0/LICENSE +22 -0
  2. pytest_authz_matrix-0.1.0/PKG-INFO +331 -0
  3. pytest_authz_matrix-0.1.0/README.md +294 -0
  4. pytest_authz_matrix-0.1.0/pyproject.toml +76 -0
  5. pytest_authz_matrix-0.1.0/setup.cfg +4 -0
  6. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/__init__.py +7 -0
  7. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/case.py +173 -0
  8. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/config.py +241 -0
  9. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/discovery.py +154 -0
  10. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/exceptions.py +13 -0
  11. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/models.py +89 -0
  12. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/plugin.py +174 -0
  13. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/py.typed +1 -0
  14. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/reporting.py +144 -0
  15. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix/templating.py +85 -0
  16. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/PKG-INFO +331 -0
  17. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/SOURCES.txt +23 -0
  18. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/dependency_links.txt +1 -0
  19. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/entry_points.txt +2 -0
  20. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/requires.txt +15 -0
  21. pytest_authz_matrix-0.1.0/src/pytest_authz_matrix.egg-info/top_level.txt +1 -0
  22. pytest_authz_matrix-0.1.0/tests/test_case.py +127 -0
  23. pytest_authz_matrix-0.1.0/tests/test_config.py +109 -0
  24. pytest_authz_matrix-0.1.0/tests/test_discovery.py +9 -0
  25. 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
+ [![CI](https://github.com/Leanstix/pytest-authz-matrix/actions/workflows/ci.yml/badge.svg)](https://github.com/Leanstix/pytest-authz-matrix/actions/workflows/ci.yml)
41
+ [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
42
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](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
+ [![CI](https://github.com/Leanstix/pytest-authz-matrix/actions/workflows/ci.yml/badge.svg)](https://github.com/Leanstix/pytest-authz-matrix/actions/workflows/ci.yml)
4
+ [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](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