acgs-auth0

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+.

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

Quick Start

Define a Scope Policy

# 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

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

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

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:

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
• Documentation
• PyPI
• Repository
• Issues
• Changelog

Constitutional Hash: 608508a9bd224290