Metadata-Version: 2.4
Name: acgs-auth0
Version: 0.1.0
Summary: Constitutional Token Governance for AI Agents — ACGS × Auth0 Token Vault
Project-URL: Homepage, https://acgs.ai
Project-URL: Documentation, https://github.com/acgs2_admin/acgs/tree/main/packages/acgs_auth0
Project-URL: Repository, https://github.com/acgs2_admin/acgs
Project-URL: Issues, https://github.com/acgs2_admin/acgs/issues
Project-URL: Changelog, https://github.com/acgs2_admin/acgs/releases
Project-URL: PyPI, https://pypi.org/project/acgs-auth0/
License: AGPL-3.0-or-later
Keywords: acgs,ai-agents,auth0,governance,maci,token-vault
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: auth0-ai-langchain>=1.0.1; extra == 'full'
Requires-Dist: auth0-ai>=1.0.2; extra == 'full'
Requires-Dist: langchain-core>=0.3.0; extra == 'full'
Requires-Dist: langgraph>=0.5.0; extra == 'full'
Requires-Dist: structlog>=24.0; extra == 'full'
Provides-Extra: langchain
Requires-Dist: auth0-ai-langchain>=1.0.1; extra == 'langchain'
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Description-Content-Type: text/markdown

# acgs-auth0

[![PyPI](https://img.shields.io/pypi/v/acgs-auth0)](https://pypi.org/project/acgs-auth0/)
[![Python](https://img.shields.io/pypi/pyversions/acgs-auth0)](https://pypi.org/project/acgs-auth0/)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

**Constitutional token governance for AI agents.**

`acgs-auth0` bridges Auth0 Token Vault with ACGS MACI governance so the
constitution, not the agent, decides which OAuth scopes can be requested. It supports
offline pre-flight checks, step-up approval for elevated scopes, and audit logging
around every exchange.

## Installation

`acgs-auth0` supports Python 3.11+.

```bash
pip install acgs-auth0
pip install acgs-auth0[langchain]
```

## Quick Start

### Define a Scope Policy

```yaml
# constitution.yaml
token_vault:
  constitutional_hash: "608508a9bd224290"
  connections:
    github:
      EXECUTIVE:
        permitted_scopes: ["read:user", "repo:read"]
        high_risk_scopes: []
      IMPLEMENTER:
        permitted_scopes: ["read:user", "repo:read", "repo:write"]
        high_risk_scopes: ["repo:write"]
```

### Validate and Exchange Tokens

```python
from acgs_auth0 import ConstitutionalTokenVault, MACIScopePolicy
from acgs_auth0.token_vault import TokenVaultRequest

policy = MACIScopePolicy.from_yaml("constitution.yaml")
vault = ConstitutionalTokenVault(policy=policy)

request = TokenVaultRequest(
    agent_id="planner",
    role="EXECUTIVE",
    connection="github",
    scopes=["repo:read"],
    refresh_token="rt_example",
    tool_name="list_issues",
)

validation = vault.validate(request)
assert validation.permitted is True

response = await vault.exchange(request)
print(response.access_token, response.scope)
```

### Step-Up for High-Risk Scopes

```python
request = TokenVaultRequest(
    agent_id="builder",
    role="IMPLEMENTER",
    connection="github",
    scopes=["repo:write"],
    refresh_token="rt_example",
)

validation = vault.validate(request)
print(validation.step_up_required)
```

### Tool Decorator

```python
from acgs_auth0 import get_token_vault_credentials, with_constitutional_token_vault

with_github = with_constitutional_token_vault(
    policy,
    connection="github",
    scopes=["read:user", "repo:read"],
)

@with_github
async def list_issues(repo: str) -> str:
    creds = get_token_vault_credentials()
    return f"using {creds['token_type']} for {repo}"
```

## Configuration

Set these environment variables for live Token Vault exchanges:

| Variable | Purpose |
| --- | --- |
| `AUTH0_DOMAIN` | Auth0 tenant domain |
| `AUTH0_CLIENT_ID` | Auth0 client ID |
| `AUTH0_CLIENT_SECRET` | Auth0 client secret |

## Key Features

- YAML-driven MACI role-to-scope governance.
- Offline validation through `MACIScopePolicy` and `ConstitutionalTokenVault.validate()`.
- Auth0 Token Vault exchange flow with optional step-up handling for elevated scopes.
- Audit primitives including `TokenAuditLog` and `TokenAccessAuditEntry`.
- Decorator-based integration for LangChain or plain Python callables.

## License

AGPL-3.0-or-later. Commercial licensing is available; contact `hello@acgs.ai`.

## Links

- [Homepage](https://acgs.ai)
- [Documentation](https://github.com/acgs2_admin/acgs/tree/main/packages/acgs_auth0)
- [PyPI](https://pypi.org/project/acgs-auth0/)
- [Repository](https://github.com/acgs2_admin/acgs)
- [Issues](https://github.com/acgs2_admin/acgs/issues)
- [Changelog](https://github.com/acgs2_admin/acgs/releases)

Constitutional Hash: `608508a9bd224290`
