Metadata-Version: 2.4
Name: heimdall-sp-validator-sdk
Version: 0.1.0
Summary: Service Provider SDK for validating Agent Identity Framework (AIF) tokens
Home-page: https://github.com/IAM-Heimdall/heimdall-sp-validator-sdk-python
Author: IAM Heimdall Team
Author-email: IAM Heimdall Team <contact@iamheimdall.com>
License: MIT
Project-URL: Homepage, https://poc.iamheimdall.com
Project-URL: Documentation, https://github.com/IAM-Heimdall/heimdall-sp-validator-sdk-python/blob/main/README.md
Project-URL: Repository, https://github.com/IAM-Heimdall/heimdall-sp-validator-sdk-python
Project-URL: Issues, https://github.com/IAM-Heimdall/heimdall-sp-validator-sdk-python/issues
Keywords: aif,agent,identity,framework,jwt,token,validation,security
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: PyJWT[cryptography]<3.0.0,>=2.8.0
Requires-Dist: httpx<1.0.0,>=0.20.0
Requires-Dist: cryptography<42.0.0,>=3.4.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "test"
Requires-Dist: httpx-mock>=0.7.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Heimdall SP Validator SDK

Python SDK for Service Providers to validate Agent Identity Framework (AIF) tokens issued by Heimdall-compliant Issuing Entities.
Verify agent tokens with cryptographic signature validation, audience checking, and revocation status - ensuring only authorized AI agents can access your services.

## Installation

```bash
pip install heimdall-sp-validator-sdk
```

## Quick Start

```python
from heimdall_sp_validator_sdk import AIFTokenValidator, AIFValidatorConfig

# Configure validator
config = AIFValidatorConfig(
    aif_core_service_url="https://poc.iamheimdall.com",
    expected_sp_audiences=["my-service-api"],
    expected_issuer_id="aif://poc-heimdall.example.com"
)

validator = AIFTokenValidator(config)

# Validate token
try:
    result = await validator.verify_atk(token_string)
    print(f"✅ Valid token for user: {result.user_id_from_aid}")
    print(f"Permissions: {result.permissions}")
except Exception as e:
    print(f"❌ Invalid token: {e}")
```

## Configuration

### Environment Variables (Recommended)

Copy `.env.example` to `.env` and configure:

```bash
AIF_CORE_SERVICE_URL=https://poc.iamheimdall.com
AIF_EXPECTED_ISSUER_ID=aif://poc-heimdall.example.com
AIF_SP_EXPECTED_AUDIENCES=my-service-api,another-service
```

Use environment-based configuration:

```python
config = AIFValidatorConfig.from_env()
validator = AIFTokenValidator(config)
```

### Configuration Options

| Parameter | Default | Description |
|-----------|---------|-------------|
| `aif_core_service_url` | Required | Base URL of AIF core service |
| `expected_sp_audiences` | Required | Your service audience ID(s) |
| `expected_issuer_id` | Required | Trusted issuer identifier |
| `jwks_cache_ttl_seconds` | 86400 | JWKS cache duration (24 hours) |
| `revocation_check_enabled` | true | Enable revocation checking |
| `revocation_check_timeout_seconds` | 5 | Revocation check timeout |
| `clock_skew_seconds` | 60 | Allowed time skew for validation |



**[More Details & Examples](DOCUMENTATION.md)**


MIT License - see [LICENSE](LICENSE) file for details.
