authzen-client 0.2.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 (48) hide show
  1. authzen_client-0.2.0/LICENSE +21 -0
  2. authzen_client-0.2.0/MANIFEST.in +4 -0
  3. authzen_client-0.2.0/PKG-INFO +89 -0
  4. authzen_client-0.2.0/README.md +72 -0
  5. authzen_client-0.2.0/docs/api.md +58 -0
  6. authzen_client-0.2.0/docs/authentication.md +104 -0
  7. authzen_client-0.2.0/docs/batch.md +68 -0
  8. authzen_client-0.2.0/docs/clients.md +57 -0
  9. authzen_client-0.2.0/docs/configuration.md +68 -0
  10. authzen_client-0.2.0/docs/development.md +56 -0
  11. authzen_client-0.2.0/docs/errors.md +37 -0
  12. authzen_client-0.2.0/docs/index.md +20 -0
  13. authzen_client-0.2.0/docs/migration.md +42 -0
  14. authzen_client-0.2.0/docs/quickstart.md +77 -0
  15. authzen_client-0.2.0/docs/search.md +81 -0
  16. authzen_client-0.2.0/examples/__init__.py +1 -0
  17. authzen_client-0.2.0/examples/async_evaluate.py +24 -0
  18. authzen_client-0.2.0/examples/async_oauth.py +44 -0
  19. authzen_client-0.2.0/examples/batch.py +30 -0
  20. authzen_client-0.2.0/examples/evaluate.py +32 -0
  21. authzen_client-0.2.0/examples/oauth.py +37 -0
  22. authzen_client-0.2.0/examples/search.py +30 -0
  23. authzen_client-0.2.0/examples/stub_pdp.py +129 -0
  24. authzen_client-0.2.0/pyproject.toml +65 -0
  25. authzen_client-0.2.0/setup.cfg +4 -0
  26. authzen_client-0.2.0/src/authzen_client/__init__.py +62 -0
  27. authzen_client-0.2.0/src/authzen_client/_client.py +201 -0
  28. authzen_client-0.2.0/src/authzen_client/async_client.py +179 -0
  29. authzen_client-0.2.0/src/authzen_client/client.py +167 -0
  30. authzen_client-0.2.0/src/authzen_client/exceptions.py +24 -0
  31. authzen_client-0.2.0/src/authzen_client/models.py +274 -0
  32. authzen_client-0.2.0/src/authzen_client/py.typed +0 -0
  33. authzen_client-0.2.0/src/authzen_client/settings.py +31 -0
  34. authzen_client-0.2.0/src/authzen_client/types.py +5 -0
  35. authzen_client-0.2.0/src/authzen_client.egg-info/PKG-INFO +89 -0
  36. authzen_client-0.2.0/src/authzen_client.egg-info/SOURCES.txt +46 -0
  37. authzen_client-0.2.0/src/authzen_client.egg-info/dependency_links.txt +1 -0
  38. authzen_client-0.2.0/src/authzen_client.egg-info/requires.txt +5 -0
  39. authzen_client-0.2.0/src/authzen_client.egg-info/top_level.txt +1 -0
  40. authzen_client-0.2.0/tests/fixtures/model_examples.json +164 -0
  41. authzen_client-0.2.0/tests/test_async_client.py +163 -0
  42. authzen_client-0.2.0/tests/test_client.py +252 -0
  43. authzen_client-0.2.0/tests/test_discovery.py +190 -0
  44. authzen_client-0.2.0/tests/test_examples.py +111 -0
  45. authzen_client-0.2.0/tests/test_extensions.py +364 -0
  46. authzen_client-0.2.0/tests/test_models.py +147 -0
  47. authzen_client-0.2.0/tests/test_oauth.py +204 -0
  48. authzen_client-0.2.0/tests/test_spec_examples.py +46 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matvii Nesterenko
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.
@@ -0,0 +1,4 @@
1
+ include LICENSE README.md
2
+ recursive-include docs *.md
3
+ recursive-include examples *.py
4
+ recursive-include tests *.py *.json
@@ -0,0 +1,89 @@
1
+ Metadata-Version: 2.4
2
+ Name: authzen-client
3
+ Version: 0.2.0
4
+ Summary: A typed Python client for the AuthZEN Authorization API.
5
+ License-Expression: MIT
6
+ Project-URL: Repository, https://github.com/kapustazh/authzen-client
7
+ Project-URL: Documentation, https://github.com/kapustazh/authzen-client/tree/main/docs
8
+ Project-URL: Issues, https://github.com/kapustazh/authzen-client/issues
9
+ Requires-Python: >=3.12
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Requires-Dist: httpx2<3,>=2.16.2
13
+ Requires-Dist: pydantic<3,>=2
14
+ Provides-Extra: oauth
15
+ Requires-Dist: authlib<2,>=1.9.8; extra == "oauth"
16
+ Dynamic: license-file
17
+
18
+ # authzen-client
19
+
20
+ A typed Python SDK for the [AuthZEN Authorization API](https://openid.net/specs/authorization-api-1_0.html).
21
+ Supports sync and async evaluation, batch requests, paginated search, discovery,
22
+ and authentication through HTTPX2 and Authlib.
23
+
24
+ ## Installation
25
+
26
+ Requires Python 3.12+. Install from a checkout in your application's environment.
27
+
28
+ ```bash
29
+ git clone https://github.com/kapustazh/authzen-client.git
30
+ cd authzen-client
31
+ python -m pip install .
32
+ ```
33
+
34
+ For OAuth Client Credentials, install the optional integration.
35
+
36
+ ```bash
37
+ python -m pip install '.[oauth]'
38
+ ```
39
+
40
+ ## Quickstart
41
+
42
+ Pass the PDP's HTTPS base URL and apply its decision in your application.
43
+
44
+ ```python
45
+ from authzen_client import Action, AuthZENClient, EvaluationRequest, Resource, Subject
46
+
47
+ request = EvaluationRequest(
48
+ subject=Subject(type="user", id="alice"),
49
+ action=Action(name="read"),
50
+ resource=Resource(type="document", id="123"),
51
+ )
52
+
53
+ with AuthZENClient(base_url="https://pdp.example.com") as client:
54
+ response = client.evaluate(request)
55
+
56
+ if response.decision:
57
+ print("Access granted")
58
+ else:
59
+ print("Access denied")
60
+ ```
61
+
62
+ Run the bundled document-service example against an in-process PDP.
63
+
64
+ ```bash
65
+ uv sync
66
+ uv run python -m examples.evaluate
67
+ ```
68
+
69
+ ```text
70
+ alice: AuthZEN project notes
71
+ bob: access denied
72
+ ```
73
+
74
+ ## Documentation
75
+
76
+ - [Quickstart and runnable examples](docs/quickstart.md)
77
+ - [Sync and async clients](docs/clients.md)
78
+ - [Batch evaluations](docs/batch.md)
79
+ - [Search and pagination](docs/search.md)
80
+ - [Authentication](docs/authentication.md)
81
+ - [Configuration and discovery](docs/configuration.md)
82
+ - [Errors](docs/errors.md)
83
+ - [API reference](docs/api.md)
84
+ - [Migrating from 0.1](docs/migration.md)
85
+ - [Development and builds](docs/development.md)
86
+
87
+ ## License
88
+
89
+ [MIT](LICENSE).
@@ -0,0 +1,72 @@
1
+ # authzen-client
2
+
3
+ A typed Python SDK for the [AuthZEN Authorization API](https://openid.net/specs/authorization-api-1_0.html).
4
+ Supports sync and async evaluation, batch requests, paginated search, discovery,
5
+ and authentication through HTTPX2 and Authlib.
6
+
7
+ ## Installation
8
+
9
+ Requires Python 3.12+. Install from a checkout in your application's environment.
10
+
11
+ ```bash
12
+ git clone https://github.com/kapustazh/authzen-client.git
13
+ cd authzen-client
14
+ python -m pip install .
15
+ ```
16
+
17
+ For OAuth Client Credentials, install the optional integration.
18
+
19
+ ```bash
20
+ python -m pip install '.[oauth]'
21
+ ```
22
+
23
+ ## Quickstart
24
+
25
+ Pass the PDP's HTTPS base URL and apply its decision in your application.
26
+
27
+ ```python
28
+ from authzen_client import Action, AuthZENClient, EvaluationRequest, Resource, Subject
29
+
30
+ request = EvaluationRequest(
31
+ subject=Subject(type="user", id="alice"),
32
+ action=Action(name="read"),
33
+ resource=Resource(type="document", id="123"),
34
+ )
35
+
36
+ with AuthZENClient(base_url="https://pdp.example.com") as client:
37
+ response = client.evaluate(request)
38
+
39
+ if response.decision:
40
+ print("Access granted")
41
+ else:
42
+ print("Access denied")
43
+ ```
44
+
45
+ Run the bundled document-service example against an in-process PDP.
46
+
47
+ ```bash
48
+ uv sync
49
+ uv run python -m examples.evaluate
50
+ ```
51
+
52
+ ```text
53
+ alice: AuthZEN project notes
54
+ bob: access denied
55
+ ```
56
+
57
+ ## Documentation
58
+
59
+ - [Quickstart and runnable examples](docs/quickstart.md)
60
+ - [Sync and async clients](docs/clients.md)
61
+ - [Batch evaluations](docs/batch.md)
62
+ - [Search and pagination](docs/search.md)
63
+ - [Authentication](docs/authentication.md)
64
+ - [Configuration and discovery](docs/configuration.md)
65
+ - [Errors](docs/errors.md)
66
+ - [API reference](docs/api.md)
67
+ - [Migrating from 0.1](docs/migration.md)
68
+ - [Development and builds](docs/development.md)
69
+
70
+ ## License
71
+
72
+ [MIT](LICENSE).
@@ -0,0 +1,58 @@
1
+ # API reference
2
+
3
+ ## Clients
4
+
5
+ AuthZENClient and AsyncAuthZENClient accept keyword-only constructor arguments.
6
+
7
+ | Argument | Default | Purpose |
8
+ | --- | --- | --- |
9
+ | base_url | Required | HTTPS PDP identifier |
10
+ | auth | None | HTTPX2 authentication |
11
+ | headers | None | Additional request headers |
12
+ | transport | None | HTTPX2 sync or async transport |
13
+ | timeout | 5.0 | Network-operation timeout, float, Timeout or None |
14
+ | limits | None | HTTPX2 connection limits |
15
+ | endpoints | None | Endpoints fallback configuration |
16
+ | http_client | None | Caller-owned HTTPX2 client |
17
+
18
+ Use the matching sync or async HTTP client and transport. Configure authentication
19
+ and network options directly on an injected http_client.
20
+
21
+ | Method | Input | Output |
22
+ | --- | --- | --- |
23
+ | evaluate | EvaluationRequest | EvaluationResponse |
24
+ | evaluate_batch | EvaluationsRequest | EvaluationsResponse |
25
+ | discover | None | PDPMetadata |
26
+ | search_resources | ResourceSearchRequest | ResourceSearchResponse |
27
+ | search_subjects | SubjectSearchRequest | SubjectSearchResponse |
28
+ | search_actions | ActionSearchRequest | ActionSearchResponse |
29
+ | iter_resources | ResourceSearchRequest | Iterator or AsyncIterator of Resource |
30
+ | iter_subjects | SubjectSearchRequest | Iterator or AsyncIterator of Subject |
31
+ | iter_actions | ActionSearchRequest | Iterator or AsyncIterator of Action |
32
+
33
+ Await async evaluate, batch, search and discover methods. Consume async iterators
34
+ with async for. Use close for the sync client and await aclose for the async one.
35
+
36
+ ## Models
37
+
38
+ - Subject and Resource require string type and id, and accept JSON properties.
39
+ - Action requires string name and accepts JSON properties.
40
+ - Context wraps a JSON object through its root attribute.
41
+ - EvaluationRequest requires subject, action and resource, with optional Context.
42
+ - Decision contains a strict boolean decision and optional Context.
43
+ - EvaluationResponse is an alias for Decision.
44
+ - Evaluation contains optional entities inherited from an EvaluationsRequest.
45
+ - EvaluationsRequest adds evaluations and EvaluationsOptions to shared defaults.
46
+ - EvaluationsResponse contains ordered evaluations or a fallback decision.
47
+ - PageRequest accepts token, non-negative limit and JSON properties.
48
+ - PageResponse requires next_token and accepts non-negative count and total.
49
+ - SubjectQuery and ResourceQuery describe the queried entity type and properties.
50
+ - Search responses contain typed results, optional PageResponse and Context.
51
+ - PDPMetadata contains the PDP identifier, evaluation endpoint, optional endpoints
52
+ and supported_capabilities.
53
+ - Endpoints contains the five fallback paths or absolute HTTPS URLs.
54
+
55
+ Models support Pydantic validation and round-trips. Unknown protocol fields are
56
+ ignored. JSON attributes inside Context and properties are retained. Batch options
57
+ retain additional JSON options. None represents an omitted optional field in the
58
+ new request models. The client omits it from the wire payload.
@@ -0,0 +1,104 @@
1
+ # Authentication
2
+
3
+ ## Headers and HTTPX2 auth
4
+
5
+ ```python
6
+ import httpx2
7
+ from authzen_client import AuthZENClient
8
+
9
+ client = AuthZENClient(
10
+ base_url="https://pdp.example.com",
11
+ headers={"Authorization": "Bearer your-access-token"},
12
+ )
13
+ client.close()
14
+
15
+ with AuthZENClient(
16
+ base_url="https://pdp.example.com",
17
+ auth=httpx2.BasicAuth("username", "password"),
18
+ ) as client:
19
+ pass
20
+ ```
21
+
22
+ Supply credentials from your application's configuration or secret store.
23
+ The application identity used to access the PDP API is independent of the Subject
24
+ in an evaluation request.
25
+
26
+ ## OAuth Client Credentials
27
+
28
+ Install the OAuth extra from the checkout.
29
+
30
+ ```bash
31
+ python -m pip install '.[oauth]'
32
+ ```
33
+
34
+ Authlib provides synchronous and asynchronous OAuth clients compatible with HTTPX2.
35
+ Pass an initialized OAuth client through http_client. The application owns its
36
+ lifecycle. Configure the token endpoint and grant type so Authlib can obtain a
37
+ new token when the previous one approaches expiry.
38
+
39
+ ```python
40
+ import os
41
+ from authlib.integrations.httpx_client import OAuth2Client
42
+ from authzen_client import AuthZENClient
43
+
44
+ token_url = os.environ["AUTHZEN_TOKEN_URL"]
45
+ with OAuth2Client(
46
+ client_id=os.environ["AUTHZEN_CLIENT_ID"],
47
+ client_secret=os.environ["AUTHZEN_CLIENT_SECRET"],
48
+ token_endpoint=token_url,
49
+ grant_type="client_credentials",
50
+ scope=os.environ.get("AUTHZEN_SCOPE"),
51
+ ) as http:
52
+ http.fetch_token(token_url, grant_type="client_credentials")
53
+ with AuthZENClient(
54
+ base_url=os.environ["AUTHZEN_PDP_URL"],
55
+ http_client=http,
56
+ ) as client:
57
+ response = client.evaluate(request)
58
+ ```
59
+
60
+ The request variable is an EvaluationRequest as in the [quickstart](quickstart.md).
61
+ Use an HTTPS token endpoint. Access tokens are held by the supplied OAuth client.
62
+
63
+ ## Asynchronous token acquisition
64
+
65
+ ```python
66
+ import os
67
+ from authlib.integrations.httpx_client import AsyncOAuth2Client
68
+ from authzen_client import AsyncAuthZENClient
69
+
70
+ token_url = os.environ["AUTHZEN_TOKEN_URL"]
71
+ async with AsyncOAuth2Client(
72
+ client_id=os.environ["AUTHZEN_CLIENT_ID"],
73
+ client_secret=os.environ["AUTHZEN_CLIENT_SECRET"],
74
+ token_endpoint=token_url,
75
+ grant_type="client_credentials",
76
+ scope=os.environ.get("AUTHZEN_SCOPE"),
77
+ ) as http:
78
+ await http.fetch_token(token_url, grant_type="client_credentials")
79
+ async with AsyncAuthZENClient(
80
+ base_url=os.environ["AUTHZEN_PDP_URL"],
81
+ http_client=http,
82
+ ) as client:
83
+ response = await client.evaluate(request)
84
+ ```
85
+
86
+ Authlib coordinates renewal for concurrent calls sharing one AsyncOAuth2Client.
87
+ The initial token request and later renewal use asynchronous HTTP operations.
88
+ For Client Credentials, a new access token is obtained using client credentials.
89
+
90
+ ## Configured-server examples
91
+
92
+ Provide AUTHZEN_PDP_URL, AUTHZEN_TOKEN_URL, AUTHZEN_CLIENT_ID and
93
+ AUTHZEN_CLIENT_SECRET in your environment. AUTHZEN_SCOPE is optional and must
94
+ match your provider configuration. The examples check user alice reading document
95
+ 123. Adapt these entities to your policies.
96
+
97
+ ```bash
98
+ uv sync --extra oauth
99
+ uv run --extra oauth python -m examples.oauth
100
+ uv run --extra oauth python -m examples.async_oauth
101
+ ```
102
+
103
+ These examples contact the configured servers. Unit tests exercise the same
104
+ Authlib integration through controlled HTTPX2 transports.
@@ -0,0 +1,68 @@
1
+ # Batch evaluations
2
+
3
+ Use evaluate_batch to send several evaluations in one HTTPS request.
4
+ The default endpoint is /access/v1/evaluations.
5
+
6
+ ## Shared defaults
7
+
8
+ ```python
9
+ from authzen_client import (
10
+ Action, AuthZENClient, Evaluation, EvaluationsRequest, Resource, Subject,
11
+ )
12
+
13
+ request = EvaluationsRequest(
14
+ subject=Subject(type="user", id="alice"),
15
+ action=Action(name="read"),
16
+ evaluations=[
17
+ Evaluation(resource=Resource(type="document", id="123")),
18
+ Evaluation(resource=Resource(type="document", id="456")),
19
+ ],
20
+ )
21
+
22
+ with AuthZENClient(base_url="https://pdp.example.com") as client:
23
+ response = client.evaluate_batch(request)
24
+
25
+ for decision in response.evaluations or []:
26
+ print(decision.decision)
27
+ ```
28
+
29
+ Each entry inherits omitted subject, action, resource and context from the
30
+ top-level request. An entry replaces a supplied entity in full. An explicitly
31
+ empty Context overrides a shared Context with an empty object.
32
+
33
+ Each effective evaluation must provide a subject, action and resource. Models
34
+ validate these requirements before sending the request.
35
+
36
+ ## Execution semantics
37
+
38
+ ```python
39
+ from authzen_client import EvaluationsOptions
40
+
41
+ options = EvaluationsOptions(evaluations_semantic="deny_on_first_deny")
42
+ ```
43
+
44
+ The supported semantics are execute_all, deny_on_first_deny and
45
+ permit_on_first_permit. Execute all is the default. A PDP may return only the
46
+ evaluated prefix. The client returns that response as sent.
47
+
48
+ Results preserve request order. Additional PDP options can be passed through
49
+ EvaluationsOptions.model_validate with JSON-compatible extra fields.
50
+
51
+ An empty or omitted evaluations array uses the protocol's single-evaluation
52
+ fallback. In that case, provide top-level subject, action and resource and read
53
+ the response decision field.
54
+
55
+ ## Errors
56
+
57
+ A general HTTP or protocol error raises an SDK exception. Individual negative
58
+ decisions, including PDP-provided error details in Context, remain ordered results.
59
+
60
+ For large workloads, choose batch sizes according to your PDP's documented limits.
61
+ Requests are sent as provided. The asynchronous client offers the same method
62
+ with await.
63
+
64
+ Run the bundled example.
65
+
66
+ ```bash
67
+ uv run python -m examples.batch
68
+ ```
@@ -0,0 +1,57 @@
1
+ # Sync and async clients
2
+
3
+ ## Synchronous use
4
+
5
+ Use one client across related operations to reuse HTTP connections.
6
+
7
+ ```python
8
+ from authzen_client import AuthZENClient
9
+
10
+ with AuthZENClient(base_url="https://pdp.example.com") as client:
11
+ response = client.evaluate(request)
12
+ ```
13
+
14
+ The request variable represents an EvaluationRequest created as in the
15
+ [quickstart](quickstart.md).
16
+
17
+ ## Asynchronous use
18
+
19
+ ```python
20
+ from authzen_client import AsyncAuthZENClient
21
+
22
+ async with AsyncAuthZENClient(base_url="https://pdp.example.com") as client:
23
+ response = await client.evaluate(request)
24
+ ```
25
+
26
+ Batch, search and discovery methods are awaited in the same way.
27
+ Use async for to consume asynchronous result iterators.
28
+
29
+ ```python
30
+ async with AsyncAuthZENClient(base_url="https://pdp.example.com") as client:
31
+ async for resource in client.iter_resources(search_request):
32
+ print(resource.id)
33
+ ```
34
+
35
+ The application controls task scheduling and concurrency. For several independent
36
+ requests, it can use asyncio.gather and an appropriate concurrency limit.
37
+
38
+ ## Your own HTTP connection
39
+
40
+ A normal client does not pass http_client. The library opens the connection and
41
+ closes it at the end of the with block.
42
+
43
+ Pass http_client when you already have an HTTPX2 client. The OAuth guide does
44
+ this with an Authlib client that gets the access token. The library sends the
45
+ access check through that connection and does not close it. You close it.
46
+
47
+ ```python
48
+ import httpx2
49
+ from authzen_client import AuthZENClient
50
+
51
+ with httpx2.Client() as http:
52
+ with AuthZENClient(base_url="https://pdp.example.com", http_client=http) as client:
53
+ response = client.evaluate(request)
54
+ ```
55
+
56
+ Set authentication, transport, timeout, and connection limits on http. The
57
+ library rejects those arguments when http_client is set.
@@ -0,0 +1,68 @@
1
+ # Configuration and discovery
2
+
3
+ ## Network settings
4
+
5
+ ```python
6
+ import httpx2
7
+ from authzen_client import AuthZENClient
8
+
9
+ client = AuthZENClient(
10
+ base_url="https://pdp.example.com",
11
+ timeout=httpx2.Timeout(10.0, connect=3.0),
12
+ limits=httpx2.Limits(max_connections=20, max_keepalive_connections=10),
13
+ )
14
+ client.close()
15
+ ```
16
+
17
+ The default timeout is five seconds per network operation. Pass None to disable
18
+ it. Connection limits use HTTPX2 defaults unless configured. Cancellation in an
19
+ async caller propagates normally.
20
+
21
+ For an injected http_client, configure these values on the HTTP client itself.
22
+ HTTPX2 uses the operating system trust store for TLS verification by default.
23
+ Custom TLS and proxy configuration can be supplied through an injected client.
24
+
25
+ ## Endpoint defaults
26
+
27
+ | Operation | Default path |
28
+ | --- | --- |
29
+ | Single evaluation | /access/v1/evaluation |
30
+ | Batch evaluations | /access/v1/evaluations |
31
+ | Subject Search | /access/v1/search/subject |
32
+ | Resource Search | /access/v1/search/resource |
33
+ | Action Search | /access/v1/search/action |
34
+
35
+ These are defaults from the AuthZEN HTTPS binding. A path prefix in base_url is
36
+ preserved when constructing endpoint URLs.
37
+
38
+ ```python
39
+ from authzen_client import AuthZENClient, Endpoints
40
+
41
+ client = AuthZENClient(
42
+ base_url="https://pdp.example.com/tenant",
43
+ endpoints=Endpoints(resources="/custom/search"),
44
+ )
45
+ client.close()
46
+ ```
47
+
48
+ The resulting resource search URL is https://pdp.example.com/tenant/custom/search.
49
+ Endpoints can also be absolute HTTPS URLs. Settings belong to each client.
50
+
51
+ ## Discovery
52
+
53
+ Call discover explicitly, or await discover on the asynchronous client.
54
+
55
+ The client retrieves unsigned JSON metadata from the AuthZEN well-known location,
56
+ validates it, and requires an exact match between policy_decision_point and the
57
+ configured base_url. For a tenant path, the well-known segment is inserted before
58
+ that path as required by the protocol.
59
+
60
+ Advertised endpoint URLs take precedence over configured fallback paths. Optional
61
+ endpoints absent from metadata retain their fallback paths as described by the
62
+ HTTPS binding. A PDP may respond with an error for an unsupported operation.
63
+ The last valid metadata is exposed through client.metadata.
64
+
65
+ A failed discovery raises an exception and preserves the previous configuration.
66
+ Metadata is replaced only after validation succeeds. Signed metadata verification
67
+ is a possible future extension. Configure a trusted PDP and protect its metadata
68
+ endpoint because discovered URLs determine where subsequent requests are sent.
@@ -0,0 +1,56 @@
1
+ # Development and builds
2
+
3
+ ## Set up
4
+
5
+ ```bash
6
+ uv sync --group dev
7
+ ```
8
+
9
+ ## Checks
10
+
11
+ ```bash
12
+ uv run pytest
13
+ uv run ruff check src tests examples
14
+ uv run ruff format --check src tests examples
15
+ uv run ty check
16
+ ```
17
+
18
+ ty checks the library, tests and examples with every diagnostic enabled as an
19
+ error. Strict equality and generic narrowing are enabled.
20
+
21
+ Tests use controlled HTTPX2 transports. OAuth tests exercise Authlib token
22
+ acquisition, renewal, errors and asynchronous concurrency. Deployed PDP/provider
23
+ integration and workload-specific performance still require verification.
24
+
25
+ ## Build and install
26
+
27
+ ```bash
28
+ uv build
29
+ python -m pip install dist/authzen_client-0.2.0-py3-none-any.whl
30
+ ```
31
+
32
+ The source distribution includes the documentation, examples, tests and JSON
33
+ fixtures. The wheel contains the library and its py.typed marker.
34
+
35
+ Project metadata and the MIT license are included in the distribution.
36
+
37
+ ## Continuous integration
38
+
39
+ `.github/workflows/ci.yml` runs on every push and pull request.
40
+
41
+ - Ruff, ty, and `uv build` run on Python 3.12. The built distributions are
42
+ uploaded as a workflow artifact.
43
+ - pytest runs on Python 3.12, 3.13, and 3.14.
44
+
45
+ `.github/workflows/publish.yml` publishes to PyPI when a GitHub release is
46
+ published. It uses PyPI trusted publishing and the `pypi` GitHub environment.
47
+ Configure that environment and the PyPI project before the first release.
48
+
49
+ ## Pull requests
50
+
51
+ Develop changes on a separate branch and submit them through a pull request.
52
+ Run the local checks before requesting review.
53
+
54
+ `.github/workflows/pr-size.yml` fails a pull request that changes more than 200
55
+ lines, counting additions and deletions. `uv.lock` is excluded. A push still
56
+ succeeds.
@@ -0,0 +1,37 @@
1
+ # Errors
2
+
3
+ | Situation | Result |
4
+ | --- | --- |
5
+ | Valid HTTP 200 with decision=false | Regular denial result |
6
+ | Connection failure or timeout | TransportError |
7
+ | Unexpected HTTP status | ProtocolError |
8
+ | Invalid content type, encoding or response model | ProtocolError |
9
+ | Authentication failure during an SDK request | ProtocolError or TransportError |
10
+ | Invalid input model | Pydantic ValidationError |
11
+ | Invalid client configuration | ValueError |
12
+
13
+ TransportError and ProtocolError inherit from AuthZENError. The original cause
14
+ is preserved through exception chaining. ProtocolError exposes response when one
15
+ is available.
16
+
17
+ ```python
18
+ from authzen_client import AuthZENError
19
+
20
+ try:
21
+ response = client.evaluate(request)
22
+ except AuthZENError:
23
+ # Choose an application policy for a failed authorization check.
24
+ raise
25
+ ```
26
+
27
+ A timeout can occur after the PDP has processed the request. The caller then has
28
+ an unknown result and must choose its failure policy. A protected operation may
29
+ be blocked while the technical error is logged or reported separately.
30
+
31
+ Initial Authlib fetch_token calls in the application raise Authlib or HTTPX2
32
+ exceptions directly. Failures while an injected OAuth client renews a token
33
+ inside an SDK operation are translated at the SDK request boundary.
34
+
35
+ The SDK performs one request per operation. Retry policy can be applied by the
36
+ caller using its overall deadline and the PDP's requirements. Take care with
37
+ credentials, tokens and sensitive attributes in logs.
@@ -0,0 +1,20 @@
1
+ # AuthZEN Client
2
+
3
+ Ask a Policy Decision Point whether a subject may perform an action on a resource.
4
+ The SDK validates protocol data and handles HTTPS communication. Your application
5
+ applies the returned decision.
6
+
7
+ The SDK implements the [AuthZEN Authorization API 1.0](https://openid.net/specs/authorization-api-1_0.html).
8
+
9
+ ## Features
10
+
11
+ - Typed Pydantic models and JSON serialization.
12
+ - Synchronous and asynchronous clients using HTTPX2.
13
+ - Single and batch evaluations, including shared defaults and short-circuit semantics.
14
+ - Subject, resource and action search with manual or automatic pagination.
15
+ - Discovery of all five API endpoints.
16
+ - Headers, HTTPX2 authentication and optional Authlib OAuth integration.
17
+ - Per-client endpoints, timeouts and connection limits.
18
+
19
+ Start with the [quickstart](quickstart.md). For migration from the HTTPX-based
20
+ release, see the [migration guide](migration.md).