agent-enrollment-protocol 0.1.0__tar.gz

agent_enrollment_protocol-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+/.conformance/aep-specs/
+/.conformance/reports/
+/.interop/
+/.mypy_cache/
+/.pytest_cache/
+/.ruff_cache/
+/.venv/
+/dist/
+/htmlcov/
+/src/*.egg-info/
+/.coverage
+/coverage.xml
+__pycache__/
+*.py[cod]

agent_enrollment_protocol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AEP Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_enrollment_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.5
+Name: agent-enrollment-protocol
+Version: 0.1.0
+Summary: Official Python SDK for the Agent Enrollment Protocol
+Project-URL: Documentation, https://www.aep.foundation/
+Project-URL: Issues, https://github.com/aep-foundation/aep-python/issues
+Project-URL: Repository, https://github.com/aep-foundation/aep-python
+Author-email: Nas Kavian <nas@inflowpay.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aep,agent,authentication,enrollment,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography<51,>=50.0.1
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: pyjwt<3,>=2.13.0
+Description-Content-Type: text/markdown
+
+# Agent Enrollment Protocol for Python
+
+[![CI](https://github.com/aep-foundation/aep-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aep-foundation/aep-python/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/agent-enrollment-protocol)](https://pypi.org/project/agent-enrollment-protocol/)
+[![Codecov](https://codecov.io/gh/aep-foundation/aep-python/graph/badge.svg)](https://codecov.io/gh/aep-foundation/aep-python)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Official Python software development kit for the
+[Agent Enrollment Protocol](https://www.aep.foundation/), the open protocol for Agent enrollment,
+Service-issued credentials, and authenticated Agent access.
+
+## Installation
+
+```sh
+python -m pip install agent-enrollment-protocol
+```
+
+Python 3.11 or newer is required. The distribution provides one typed package with modules for each
+integration role:
+
+| Goal | Module |
+| --- | --- |
+| Use protocol models, validation, identity, and assertions | `agent_enrollment_protocol.core` |
+| Inspect, enroll with, and authenticate to Services | `agent_enrollment_protocol.agent` |
+| Integrate enrollment and authentication into a Service | `agent_enrollment_protocol.service` |
+| Host managed Agent identities and delegated signing | `agent_enrollment_protocol.platform` |
+
+Core is synchronous and transport-independent. Agent, Service, Platform, and their integration
+interfaces are asynchronous. Applications provide durable stores and security policy through typed
+protocols.
+
+Framework integrations are optional and remain separate from Core and role behavior.
+
+## Runnable examples
+
+The repository includes self-contained examples that exercise real signed protocol flows without
+external infrastructure:
+
+```sh
+uv run python examples/agent_service.py
+uv run python examples/hosted_platform.py
+```
+
+The first example composes an Agent, Service, every built-in credential profile, protected resource,
+and the framework-neutral ASGI adapter. The second demonstrates hosted identity Platform discovery,
+Service DID resolution, provisioning, DID publication, delegated signing, and identity listing. See
+[`examples/README.md`](./examples/README.md) for the integration boundaries and production
+replacements.
+
+The Service module includes stored credential profiles for each built-in Grant Type:
+
+| Grant Type | Factory |
+| --- | --- |
+| API key | `stored_api_key_grant_type()` |
+| Basic | `stored_basic_grant_type()` |
+| OAuth Bearer | `stored_oauth_bearer_grant_type()` |
+
+Each factory accepts application-owned credential issuance and storage implementations. The included
+memory store is intended for examples and local development.
+
+Concrete Grant Types and extensions can define additional Grant and Revoke request members. Pass
+those members through `GrantOptions.parameters` or `RevokeOptions.parameters`; the Agent retains
+control of the standard Grant Type and Revoke selector fields.
+
+## Service ASGI integration
+
+`agent_enrollment_protocol.adapters` provides a framework-neutral ASGI integration with no
+additional dependency. `AepAsgiApplication` serves Inspect and every command advertised by the
+Service. It enforces the command methods, media type, request-body limit, and idempotency header
+boundary, and supplies cache metadata and conditional requests for Inspect.
+
+`AepAuthenticationMiddleware` protects a downstream ASGI application and exposes the authenticated
+Agent principal through `principal_from_scope()`. Place the protocol application outside the
+authentication middleware so AEP's own command routes remain directly accessible:
+
+```python
+from agent_enrollment_protocol.adapters import (
+    AepAsgiApplication,
+    AepAuthenticationMiddleware,
+    principal_from_scope,
+)
+
+protected_application = AepAuthenticationMiddleware(
+    application,
+    service,
+    resource_origin="https://service.example",
+)
+asgi_application = AepAsgiApplication(service, protected_application)
+```
+
+The downstream application can obtain its immutable principal from the ASGI scope:
+
+```python
+principal = principal_from_scope(scope)
+if principal is None:
+    raise RuntimeError("The route requires AEP authentication")
+```
+
+Use a separate unprotected application branch for public resources. For local development,
+`allow_insecure_loopback=True` permits an HTTP `localhost` or loopback resource origin; production
+origins require HTTPS.
+
+## Agent with a hosted identity Platform
+
+`PlatformIdentityProvider` lets an Agent use a remote AEP Platform for Service-scoped identity
+custody and delegated assertion signing. It discovers the Platform, recovers an existing active
+identity before provisioning one, caches discovery metadata according to HTTP cache directives,
+and supplies the resulting signer directly to `Agent`.
+
+```python
+import os
+
+from agent_enrollment_protocol.agent import (
+    Agent,
+    AgentOptions,
+    PlatformIdentityProvider,
+    PlatformIdentityProviderOptions,
+)
+
+
+async def authentication_headers() -> dict[str, str]:
+    return {"Authorization": f"Bearer {os.environ['AEP_PLATFORM_ACCESS_TOKEN']}"}
+
+
+async with PlatformIdentityProvider(
+    PlatformIdentityProviderOptions(
+        authentication_headers=authentication_headers,
+        platform_url="https://platform.example",
+    )
+) as identities:
+    async with Agent(AgentOptions(identity_provider=identities)) as agent:
+        result = await agent.service("https://service.example").enroll()
+```
+
+The Platform authentication callback is evaluated for each private request so applications can
+refresh short-lived credentials. Supply `pending_sign_resolver` when the Platform can return
+`202 Accepted` during delegated signing. The resolver receives the immutable retry interval and
+opaque Platform context; returning updated context starts the next signing stage with a distinct
+idempotency key. Without a resolver, pending signing raises `PlatformSignPendingError` for the
+application to continue explicitly.
+
+## Hosted identity Platform
+
+`agent_enrollment_protocol.platform` implements discovery, Service-scoped Agent identity
+provisioning, DID document publication, identity listing and lifecycle, delegated signing, and
+optional hosted verification.
+
+Applications supply caller authorization, Service DID resolution, key custody, and durable stores.
+The included memory stores are suitable for local development, not production key custody or
+durable idempotency.
+
+```python
+from datetime import timedelta
+
+from agent_enrollment_protocol.core import SigningAlgorithm
+from agent_enrollment_protocol.platform import DiscoveryOptions, Platform, PlatformOptions
+
+platform = Platform(
+    PlatformOptions(
+        authorizer=authorizer,
+        did_host="platform.example",
+        did_url_template="https://platform.example/agents/{agent_did_id}/did.json",
+        discovery=DiscoveryOptions(
+            endpoint_base="/v1/aep",
+            lifecycle_endpoint="/v1/aep/agent-identities/{agent_identity_id}",
+            list_endpoint="/v1/aep/agent-identities",
+            platform_name="Example Platform",
+            provision_endpoint="/v1/aep/agent-identities",
+            sign_endpoint="/v1/aep/agent-identities/{agent_identity_id}/sign",
+        ),
+        key_store=key_store,
+        maximum_lifetime=timedelta(minutes=5),
+        service_did_resolver=service_did_resolver,
+        signing_algorithms=(SigningAlgorithm.ES256,),
+    )
+)
+```
+
+Map `platform.discovery()` to `/.well-known/aep-platform` and the remaining methods to the paths
+advertised by `DiscoveryOptions`. Authenticate private Platform routes before constructing their
+`RequestContext`; the Platform also invokes the supplied authorizer for every private operation.
+Enable hosted verification only with a replay store.
+
+## Development
+
+Install the locked development environment and run the complete merge gate:
+
+```sh
+uv sync --all-groups --locked
+make verify
+```
+
+Run the shared Agent, Service, and Platform conformance suites against the public Python APIs:
+
+```sh
+make conformance
+```
+
+The command reads the adjacent `../aep-specs` checkout by default and writes role reports to
+`.conformance/reports/`. Set `AEP_SPECS_DIR` when the specifications are checked out elsewhere.
+
+Run bidirectional Agent, Service, and Platform interoperability against the Node.js SDK:
+
+```sh
+make interoperability
+```
+
+The command reads the adjacent `../aep-node` checkout by default and writes a four-row evidence
+report to `.interop/reports/aep-python-node-interoperability.json`. Set `AEP_NODE_DIR` when the
+Node.js SDK is checked out elsewhere.
+
+See [`aep-specs`](https://github.com/aep-foundation/aep-specs) for the normative drafts, schemas,
+registries, examples, and test vectors.
+
+## Releases
+
+Maintainers run the `Release` workflow from `main`. It verifies the package and a clean consumer,
+runs shared conformance and Node.js interoperability, publishes through PyPI Trusted Publishing,
+attests the distributions, and creates the matching tag and GitHub release with the verification
+reports.
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for vulnerability reporting.
+
+## License
+
+MIT.

agent_enrollment_protocol-0.1.0/README.md

@@ -0,0 +1,229 @@
+# Agent Enrollment Protocol for Python
+
+[![CI](https://github.com/aep-foundation/aep-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aep-foundation/aep-python/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/agent-enrollment-protocol)](https://pypi.org/project/agent-enrollment-protocol/)
+[![Codecov](https://codecov.io/gh/aep-foundation/aep-python/graph/badge.svg)](https://codecov.io/gh/aep-foundation/aep-python)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Official Python software development kit for the
+[Agent Enrollment Protocol](https://www.aep.foundation/), the open protocol for Agent enrollment,
+Service-issued credentials, and authenticated Agent access.
+
+## Installation
+
+```sh
+python -m pip install agent-enrollment-protocol
+```
+
+Python 3.11 or newer is required. The distribution provides one typed package with modules for each
+integration role:
+
+| Goal | Module |
+| --- | --- |
+| Use protocol models, validation, identity, and assertions | `agent_enrollment_protocol.core` |
+| Inspect, enroll with, and authenticate to Services | `agent_enrollment_protocol.agent` |
+| Integrate enrollment and authentication into a Service | `agent_enrollment_protocol.service` |
+| Host managed Agent identities and delegated signing | `agent_enrollment_protocol.platform` |
+
+Core is synchronous and transport-independent. Agent, Service, Platform, and their integration
+interfaces are asynchronous. Applications provide durable stores and security policy through typed
+protocols.
+
+Framework integrations are optional and remain separate from Core and role behavior.
+
+## Runnable examples
+
+The repository includes self-contained examples that exercise real signed protocol flows without
+external infrastructure:
+
+```sh
+uv run python examples/agent_service.py
+uv run python examples/hosted_platform.py
+```
+
+The first example composes an Agent, Service, every built-in credential profile, protected resource,
+and the framework-neutral ASGI adapter. The second demonstrates hosted identity Platform discovery,
+Service DID resolution, provisioning, DID publication, delegated signing, and identity listing. See
+[`examples/README.md`](./examples/README.md) for the integration boundaries and production
+replacements.
+
+The Service module includes stored credential profiles for each built-in Grant Type:
+
+| Grant Type | Factory |
+| --- | --- |
+| API key | `stored_api_key_grant_type()` |
+| Basic | `stored_basic_grant_type()` |
+| OAuth Bearer | `stored_oauth_bearer_grant_type()` |
+
+Each factory accepts application-owned credential issuance and storage implementations. The included
+memory store is intended for examples and local development.
+
+Concrete Grant Types and extensions can define additional Grant and Revoke request members. Pass
+those members through `GrantOptions.parameters` or `RevokeOptions.parameters`; the Agent retains
+control of the standard Grant Type and Revoke selector fields.
+
+## Service ASGI integration
+
+`agent_enrollment_protocol.adapters` provides a framework-neutral ASGI integration with no
+additional dependency. `AepAsgiApplication` serves Inspect and every command advertised by the
+Service. It enforces the command methods, media type, request-body limit, and idempotency header
+boundary, and supplies cache metadata and conditional requests for Inspect.
+
+`AepAuthenticationMiddleware` protects a downstream ASGI application and exposes the authenticated
+Agent principal through `principal_from_scope()`. Place the protocol application outside the
+authentication middleware so AEP's own command routes remain directly accessible:
+
+```python
+from agent_enrollment_protocol.adapters import (
+    AepAsgiApplication,
+    AepAuthenticationMiddleware,
+    principal_from_scope,
+)
+
+protected_application = AepAuthenticationMiddleware(
+    application,
+    service,
+    resource_origin="https://service.example",
+)
+asgi_application = AepAsgiApplication(service, protected_application)
+```
+
+The downstream application can obtain its immutable principal from the ASGI scope:
+
+```python
+principal = principal_from_scope(scope)
+if principal is None:
+    raise RuntimeError("The route requires AEP authentication")
+```
+
+Use a separate unprotected application branch for public resources. For local development,
+`allow_insecure_loopback=True` permits an HTTP `localhost` or loopback resource origin; production
+origins require HTTPS.
+
+## Agent with a hosted identity Platform
+
+`PlatformIdentityProvider` lets an Agent use a remote AEP Platform for Service-scoped identity
+custody and delegated assertion signing. It discovers the Platform, recovers an existing active
+identity before provisioning one, caches discovery metadata according to HTTP cache directives,
+and supplies the resulting signer directly to `Agent`.
+
+```python
+import os
+
+from agent_enrollment_protocol.agent import (
+    Agent,
+    AgentOptions,
+    PlatformIdentityProvider,
+    PlatformIdentityProviderOptions,
+)
+
+
+async def authentication_headers() -> dict[str, str]:
+    return {"Authorization": f"Bearer {os.environ['AEP_PLATFORM_ACCESS_TOKEN']}"}
+
+
+async with PlatformIdentityProvider(
+    PlatformIdentityProviderOptions(
+        authentication_headers=authentication_headers,
+        platform_url="https://platform.example",
+    )
+) as identities:
+    async with Agent(AgentOptions(identity_provider=identities)) as agent:
+        result = await agent.service("https://service.example").enroll()
+```
+
+The Platform authentication callback is evaluated for each private request so applications can
+refresh short-lived credentials. Supply `pending_sign_resolver` when the Platform can return
+`202 Accepted` during delegated signing. The resolver receives the immutable retry interval and
+opaque Platform context; returning updated context starts the next signing stage with a distinct
+idempotency key. Without a resolver, pending signing raises `PlatformSignPendingError` for the
+application to continue explicitly.
+
+## Hosted identity Platform
+
+`agent_enrollment_protocol.platform` implements discovery, Service-scoped Agent identity
+provisioning, DID document publication, identity listing and lifecycle, delegated signing, and
+optional hosted verification.
+
+Applications supply caller authorization, Service DID resolution, key custody, and durable stores.
+The included memory stores are suitable for local development, not production key custody or
+durable idempotency.
+
+```python
+from datetime import timedelta
+
+from agent_enrollment_protocol.core import SigningAlgorithm
+from agent_enrollment_protocol.platform import DiscoveryOptions, Platform, PlatformOptions
+
+platform = Platform(
+    PlatformOptions(
+        authorizer=authorizer,
+        did_host="platform.example",
+        did_url_template="https://platform.example/agents/{agent_did_id}/did.json",
+        discovery=DiscoveryOptions(
+            endpoint_base="/v1/aep",
+            lifecycle_endpoint="/v1/aep/agent-identities/{agent_identity_id}",
+            list_endpoint="/v1/aep/agent-identities",
+            platform_name="Example Platform",
+            provision_endpoint="/v1/aep/agent-identities",
+            sign_endpoint="/v1/aep/agent-identities/{agent_identity_id}/sign",
+        ),
+        key_store=key_store,
+        maximum_lifetime=timedelta(minutes=5),
+        service_did_resolver=service_did_resolver,
+        signing_algorithms=(SigningAlgorithm.ES256,),
+    )
+)
+```
+
+Map `platform.discovery()` to `/.well-known/aep-platform` and the remaining methods to the paths
+advertised by `DiscoveryOptions`. Authenticate private Platform routes before constructing their
+`RequestContext`; the Platform also invokes the supplied authorizer for every private operation.
+Enable hosted verification only with a replay store.
+
+## Development
+
+Install the locked development environment and run the complete merge gate:
+
+```sh
+uv sync --all-groups --locked
+make verify
+```
+
+Run the shared Agent, Service, and Platform conformance suites against the public Python APIs:
+
+```sh
+make conformance
+```
+
+The command reads the adjacent `../aep-specs` checkout by default and writes role reports to
+`.conformance/reports/`. Set `AEP_SPECS_DIR` when the specifications are checked out elsewhere.
+
+Run bidirectional Agent, Service, and Platform interoperability against the Node.js SDK:
+
+```sh
+make interoperability
+```
+
+The command reads the adjacent `../aep-node` checkout by default and writes a four-row evidence
+report to `.interop/reports/aep-python-node-interoperability.json`. Set `AEP_NODE_DIR` when the
+Node.js SDK is checked out elsewhere.
+
+See [`aep-specs`](https://github.com/aep-foundation/aep-specs) for the normative drafts, schemas,
+registries, examples, and test vectors.
+
+## Releases
+
+Maintainers run the `Release` workflow from `main`. It verifies the package and a clean consumer,
+runs shared conformance and Node.js interoperability, publishes through PyPI Trusted Publishing,
+attests the distributions, and creates the matching tag and GitHub release with the verification
+reports.
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for vulnerability reporting.
+
+## License
+
+MIT.

agent_enrollment_protocol-0.1.0/examples/README.md

@@ -0,0 +1,31 @@
+# Examples
+
+These examples run locally without external infrastructure. They use real signed assertions and the
+public software development kit interfaces, while keeping identities, enrollments, credentials, and
+keys in memory.
+
+| Example | Demonstrates |
+| --- | --- |
+| [`agent_service.py`](./agent_service.py) | Agent inspection, enrollment, API-key, Basic, and OAuth Bearer grants, authenticated Service access, credential revocation, and rejected reuse through the ASGI adapter |
+| [`hosted_platform.py`](./hosted_platform.py) | Hosted identity Platform discovery, Service DID resolution, provisioning, DID document publication, delegated signing, identity listing, and lifecycle management |
+
+Run them from the repository root after installing the development environment:
+
+```sh
+uv sync --all-groups --locked
+uv run python examples/agent_service.py
+uv run python examples/hosted_platform.py
+```
+
+Both examples resolve `did:web` documents through HTTP clients using HTTPS URLs. Their in-memory
+transports make the examples deterministic without bypassing DID resolution. Production
+integrations use a normal HTTP client with their cache and network policy. Replace all memory stores
+with durable implementations before deployment.
+
+The Agent and Service example runs every built-in credential profile. Each profile supplies an issuer
+callback and the same `ServiceCredentialStore` to its corresponding `stored_*_grant_type()` factory.
+The example authenticates with each issued credential, revokes it, and confirms that reuse is rejected.
+
+The Platform example deliberately keeps its private key in process. A production Platform supplies a
+`KeyStore` backed by its key-management system and maps the Platform methods to authenticated HTTP
+routes.