Metadata-Version: 2.4
Name: oauth-identity-chaining-sdk
Version: 0.1.0
Summary: Python SDK for OAuth Identity Chaining (draft-oauth-identity-chaining) with actor provenance
Project-URL: Homepage, https://github.com/authsec-ai/oauth-identity-chaining-sdk
Project-URL: Documentation, https://github.com/authsec-ai/oauth-identity-chaining-sdk#readme
Project-URL: Repository, https://github.com/authsec-ai/oauth-identity-chaining-sdk
Project-URL: Changelog, https://github.com/authsec-ai/oauth-identity-chaining-sdk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/authsec-ai/oauth-identity-chaining-sdk/issues
Author-email: OAuth Identity Chaining Contributors <dev@authsec.ai>
License: MIT
License-File: LICENSE
Keywords: ai-agents,delegation,identity-chaining,jwt,multi-hop,oauth,rfc8693
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.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.10
Requires-Dist: httpx>=0.20.0
Requires-Dist: pyjwt>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# OAuth Identity Chaining SDK (`oauth-identity-chaining-sdk`)

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Protocol](https://img.shields.io/badge/RFC-8693%20Token%20Exchange-orange.svg)](https://datatracker.ietf.org/doc/html/rfc8693)

A Python client library implementing cross-application authentication, dynamic permission downscoping, and call chain tracking conforming to **draft-ietf-oauth-identity-chaining** (OAuth Identity and Authorization Chaining Across Domains) and **RFC 8693 (Token Exchange)**.

This SDK allows autonomous AI agents and microservices to pass credentials downstream under the Principle of Least Privilege, preserving tamper-proof actor provenance (`Principal ──> Agent A ──> Agent B`) via nested JWT `act` (actor) claims.

---

## ⚡ Installation

Install the library using pip:
```bash
pip install oauth-identity-chaining-sdk
```

---

## 🚀 Key Features

* 🔄 **RFC 8693 Token Exchange**: Exchange a broad subject token for a narrow downstream token using `exchange_token`.
* 🛡️ **Permission Narrowing**: Intersection check ensures delegated tokens hold a strict subset of delegator rights.
* 🔍 **Multi-Hop Actor Provenance**: Parse and traverse nested `act` claims to verify call chain lineages.
* 🛑 **Least Privilege Guards**: Enforce audience matches, expiration timestamps, and strict delegation depth limits.
* 💡 **Mock Mode Fallback**: Bypasses external server requests during local development or offline simulations.

---

## 📖 Quick Start

### 1. Fetching a Root Delegation Token
```python
import os
from oauth_identity_chaining import ChainingClient, ChainingConfig

# Setup client. Automatically falls back to mock mode if env variables are missing.
client = ChainingClient()

# Get the initial delegation token for Agent A
root_token = client.get_root_token()
print(f"Root Token: {root_token[:30]}...")
```

### 2. Performing a Scoped Token Exchange (Delegation Chain)
Agent A delegates `users:read` authority to Agent B (`AGENT_B_CLIENT_ID`):
```python
agent_b_id = "c7f3a2b1-5d4e-4f8a-9c6b-2e1d0f7a8b3c"

exchange_res = client.exchange_token(
    subject_token=root_token,
    target_client_id=agent_b_id,
    permissions=["users:read"],
    ttl=300,
    audience=["authsec-secure-vault"]
)

chained_token = exchange_res["token"]
print(f"Chained Token: {chained_token[:30]}...")
```

### 3. Parsing and Rendering Actor Provenance
Upstream services or resource servers can verify the token's lineage and print the visual actor tree:
```python
from oauth_identity_chaining import verify_token_provenance

# Verify claims and extract provenance chain
chain = verify_token_provenance(
    chained_token,
    expected_audience="authsec-secure-vault",
    max_depth=1,
    verify_signature=False  # Set to True and provide jwks_client in production
)

# Print visual chain tree
print("Actor Call Chain Lineage:")
print(chain.render_tree())
# Output:
# [Principal User]
#   └── spiffe://localhost/ns/default/sa/crewai (Client ID: 6656be3a-b687-4f2e-9e83-11abe5eaec26)
#         └── spiffe://localhost/ns/default/sa/agent-b (Client ID: c7f3a2b1-5d4e-4f8a-9c6b-2e1d0f7a8b3c)  <-- ACTIVE BEARER

print(f"Delegation Depth: {chain.depth}")
print(f"Active Bearer: {chain.active_bearer.sub}")
print(f"Root Delegator: {chain.root_subject.sub}")
```

### 4. Downstream API Call
Agent B calls the Secure Vault using the chained token:
```python
vault_response = client.request_secure_api(
    endpoint="http://localhost:7469/secure-vault/metrics",
    token=chained_token,
    method="GET"
)
print(vault_response)
```

---

## 🛠️ Offline Mock Fallback
If `AUTHSEC_BASE_URL` or `AUTHSEC_AGENT_CLIENT_ID` are not configured:
* The client runs in offline simulation mode automatically.
* Token endpoints return locally-generated HS256 tokens carrying valid `act` claims.
* Downstream endpoints (`secure-vault/metrics` and `secure-vault/records`) return pre-defined mock JSON structures.
