apoa 0.1.0__tar.gz

apoa-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: apoa
+Version: 0.1.0
+Summary: Python SDK for the Agentic Power of Attorney (APOA) standard
+Author-email: Agentic POA <agenticpoa@users.noreply.github.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/agenticpoa/apoa
+Project-URL: Documentation, https://github.com/agenticpoa/apoa/tree/main/sdk-python
+Project-URL: Repository, https://github.com/agenticpoa/apoa
+Project-URL: Issues, https://github.com/agenticpoa/apoa/issues
+Keywords: authorization,ai-agents,delegation,jwt,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: PyJWT[crypto]>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# APOA Python SDK
+
+Python SDK for the [Agentic Power of Attorney (APOA)](https://github.com/agenticpoa/apoa) standard -- authorization infrastructure for AI agents.
+
+## Install
+
+```bash
+pip install apoa
+```
+
+## Quick Start
+
+```python
+from apoa import (
+    APOADefinition, Agent, BrowserSessionConfig, Principal,
+    Rule, ServiceAuthorization, SigningOptions,
+    create_client, generate_key_pair,
+)
+
+# Generate keys and create a client
+private_key, public_key = generate_key_pair()
+client = create_client(default_private_key=private_key)
+
+# Create a signed authorization token
+token = client.create_token(APOADefinition(
+    principal=Principal(id="did:apoa:you"),
+    agent=Agent(id="did:apoa:your-agent", name="HomeBot Pro"),
+    services=[ServiceAuthorization(
+        service="nationwidemortgage.com",
+        scopes=["rate_lock:read", "documents:read"],
+        constraints={"signing": False},
+        access_mode="browser",
+        browser_config=BrowserSessionConfig(
+            allowed_urls=["https://portal.nationwidemortgage.com/*"],
+            credential_vault_ref="1password://vault/mortgage-portal",
+        ),
+    )],
+    rules=[Rule(id="no-signing", description="Never sign anything", enforcement="hard")],
+    expires="2026-09-01",
+))
+
+# Authorize actions
+result = client.authorize(token, "nationwidemortgage.com", "rate_lock:read")
+print(result.authorized)  # True
+
+result = client.authorize(token, "nationwidemortgage.com", "documents:sign")
+print(result.authorized)  # False
+```
+
+## Features
+
+- **Token lifecycle**: create, sign (Ed25519/ES256), validate, parse
+- **Scope matching**: hierarchical pattern matching (`appointments:*` matches `appointments:read`)
+- **Constraint enforcement**: boolean denial at the SDK level, rich constraints at the protocol level
+- **Authorization**: revocation + scope + constraints + hard/soft rules in one call
+- **Delegation chains**: parent-to-child with cryptographically enforced attenuation
+- **Cascade revocation**: revoke parent, kill all children instantly
+- **Audit trail**: append-only action log per token
+- **Cross-SDK compatibility**: tokens created by the TypeScript SDK validate in Python and vice versa
+
+## Cross-SDK Compatibility
+
+Tokens are JWTs. A token signed by `@apoa/core` (TypeScript) validates in `apoa` (Python) and vice versa. The serialization layer handles camelCase (JWT payload) to snake_case (Python) mapping automatically.
+
+## API
+
+Two usage styles:
+
+```python
+# Style 1: Client instance (recommended)
+client = create_client(default_private_key=key)
+client.authorize(token, "service.com", "action:read")
+
+# Style 2: Standalone imports
+from apoa import authorize, check_scope
+check_scope(token, "service.com", "action:read")
+```
+
+See the [full spec](https://github.com/agenticpoa/apoa/blob/main/SPEC.md) and [TypeScript SDK](https://github.com/agenticpoa/apoa/tree/main/sdk) for more.
+
+## License
+
+Apache 2.0

apoa-0.1.0/README.md

@@ -0,0 +1,83 @@
+# APOA Python SDK
+
+Python SDK for the [Agentic Power of Attorney (APOA)](https://github.com/agenticpoa/apoa) standard -- authorization infrastructure for AI agents.
+
+## Install
+
+```bash
+pip install apoa
+```
+
+## Quick Start
+
+```python
+from apoa import (
+    APOADefinition, Agent, BrowserSessionConfig, Principal,
+    Rule, ServiceAuthorization, SigningOptions,
+    create_client, generate_key_pair,
+)
+
+# Generate keys and create a client
+private_key, public_key = generate_key_pair()
+client = create_client(default_private_key=private_key)
+
+# Create a signed authorization token
+token = client.create_token(APOADefinition(
+    principal=Principal(id="did:apoa:you"),
+    agent=Agent(id="did:apoa:your-agent", name="HomeBot Pro"),
+    services=[ServiceAuthorization(
+        service="nationwidemortgage.com",
+        scopes=["rate_lock:read", "documents:read"],
+        constraints={"signing": False},
+        access_mode="browser",
+        browser_config=BrowserSessionConfig(
+            allowed_urls=["https://portal.nationwidemortgage.com/*"],
+            credential_vault_ref="1password://vault/mortgage-portal",
+        ),
+    )],
+    rules=[Rule(id="no-signing", description="Never sign anything", enforcement="hard")],
+    expires="2026-09-01",
+))
+
+# Authorize actions
+result = client.authorize(token, "nationwidemortgage.com", "rate_lock:read")
+print(result.authorized)  # True
+
+result = client.authorize(token, "nationwidemortgage.com", "documents:sign")
+print(result.authorized)  # False
+```
+
+## Features
+
+- **Token lifecycle**: create, sign (Ed25519/ES256), validate, parse
+- **Scope matching**: hierarchical pattern matching (`appointments:*` matches `appointments:read`)
+- **Constraint enforcement**: boolean denial at the SDK level, rich constraints at the protocol level
+- **Authorization**: revocation + scope + constraints + hard/soft rules in one call
+- **Delegation chains**: parent-to-child with cryptographically enforced attenuation
+- **Cascade revocation**: revoke parent, kill all children instantly
+- **Audit trail**: append-only action log per token
+- **Cross-SDK compatibility**: tokens created by the TypeScript SDK validate in Python and vice versa
+
+## Cross-SDK Compatibility
+
+Tokens are JWTs. A token signed by `@apoa/core` (TypeScript) validates in `apoa` (Python) and vice versa. The serialization layer handles camelCase (JWT payload) to snake_case (Python) mapping automatically.
+
+## API
+
+Two usage styles:
+
+```python
+# Style 1: Client instance (recommended)
+client = create_client(default_private_key=key)
+client.authorize(token, "service.com", "action:read")
+
+# Style 2: Standalone imports
+from apoa import authorize, check_scope
+check_scope(token, "service.com", "action:read")
+```
+
+See the [full spec](https://github.com/agenticpoa/apoa/blob/main/SPEC.md) and [TypeScript SDK](https://github.com/agenticpoa/apoa/tree/main/sdk) for more.
+
+## License
+
+Apache 2.0

apoa-0.1.0/apoa/__init__.py

@@ -0,0 +1,144 @@
+"""APOA SDK -- Agentic Power of Attorney for Python."""
+
+# Client
+from .client import APOAClient, create_client
+
+# Token lifecycle
+from .token import create_token, parse_definition, validate_token
+
+# Authorization
+from .authorization import authorize
+from .constraints import check_constraint
+from .scope import check_scope, match_scope
+
+# Delegation
+from .delegation import delegate, verify_chain
+
+# Revocation
+from .revocation import (
+    MemoryRevocationStore,
+    RevocationStore,
+    cascade_revoke,
+    is_revoked,
+    revoke,
+)
+
+# Audit
+from .audit import (
+    AuditStore,
+    MemoryAuditStore,
+    get_audit_trail,
+    get_audit_trail_by_service,
+    log_action,
+)
+
+# Crypto
+from .crypto import generate_key_pair
+
+# Time utilities
+from .utils import is_before_not_before, is_expired
+
+# Types
+from .types import (
+    APIAccessConfig,
+    APOADefinition,
+    APOAToken,
+    Agent,
+    AgentProvider,
+    AuditEntry,
+    AuditQueryOptions,
+    AuthorizationResult,
+    BrowserSessionConfig,
+    ChainVerificationResult,
+    DelegationDefinition,
+    LegalFramework,
+    Principal,
+    RevocationRecord,
+    Rule,
+    RuleViolation,
+    ScopeCheckResult,
+    ServiceAuthorization,
+    SigningOptions,
+    ValidationOptions,
+    ValidationResult,
+)
+
+# Errors
+from .errors import (
+    APOAError,
+    AttenuationViolationError,
+    ChainVerificationError,
+    DefinitionValidationError,
+    MetadataValidationError,
+    RevocationError,
+    RuleEnforcementError,
+    ScopeViolationError,
+    TokenExpiredError,
+)
+
+__all__ = [
+    # Client
+    "APOAClient",
+    "create_client",
+    # Token lifecycle
+    "create_token",
+    "validate_token",
+    "parse_definition",
+    # Authorization
+    "authorize",
+    "check_scope",
+    "match_scope",
+    "check_constraint",
+    # Delegation
+    "delegate",
+    "verify_chain",
+    # Revocation
+    "revoke",
+    "is_revoked",
+    "cascade_revoke",
+    "RevocationStore",
+    "MemoryRevocationStore",
+    # Audit
+    "log_action",
+    "get_audit_trail",
+    "get_audit_trail_by_service",
+    "AuditStore",
+    "MemoryAuditStore",
+    # Crypto
+    "generate_key_pair",
+    # Time
+    "is_expired",
+    "is_before_not_before",
+    # Types
+    "Principal",
+    "Agent",
+    "AgentProvider",
+    "LegalFramework",
+    "BrowserSessionConfig",
+    "APIAccessConfig",
+    "ServiceAuthorization",
+    "Rule",
+    "RuleViolation",
+    "APOADefinition",
+    "APOAToken",
+    "ScopeCheckResult",
+    "AuthorizationResult",
+    "ValidationResult",
+    "RevocationRecord",
+    "AuditEntry",
+    "AuditQueryOptions",
+    "DelegationDefinition",
+    "ChainVerificationResult",
+    "SigningOptions",
+    "ValidationOptions",
+    # Errors
+    "APOAError",
+    "TokenExpiredError",
+    "ScopeViolationError",
+    "AttenuationViolationError",
+    "RevocationError",
+    "ChainVerificationError",
+    "MetadataValidationError",
+    "RuleEnforcementError",
+    "DefinitionValidationError",
+]

apoa-0.1.0/apoa/audit.py

@@ -0,0 +1,100 @@
+"""Audit store and logging."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Protocol
+
+from .types import AuditEntry, AuditQueryOptions
+
+
+class AuditStore(Protocol):
+    def append(self, entry: AuditEntry) -> None: ...
+    def query(self, token_id: str, options: AuditQueryOptions | None = None) -> list[AuditEntry]: ...
+    def query_by_service(self, service: str, options: AuditQueryOptions | None = None) -> list[AuditEntry]: ...
+
+
+class MemoryAuditStore:
+    """In-memory audit store for dev/testing."""
+
+    def __init__(self) -> None:
+        self._entries: list[AuditEntry] = []
+
+    def append(self, entry: AuditEntry) -> None:
+        self._entries.append(entry)
+
+    def query(self, token_id: str, options: AuditQueryOptions | None = None) -> list[AuditEntry]:
+        results = [e for e in self._entries if e.token_id == token_id]
+        return _apply_query_options(results, options)
+
+    def query_by_service(self, service: str, options: AuditQueryOptions | None = None) -> list[AuditEntry]:
+        results = [e for e in self._entries if e.service == service]
+        return _apply_query_options(results, options)
+
+
+def _apply_query_options(entries: list[AuditEntry], options: AuditQueryOptions | None) -> list[AuditEntry]:
+    if options is None:
+        return entries
+
+    results = entries
+    if options.from_time:
+        results = [e for e in results if e.timestamp >= options.from_time]
+    if options.to_time:
+        results = [e for e in results if e.timestamp <= options.to_time]
+    if options.action:
+        results = [e for e in results if e.action == options.action]
+    if options.service:
+        results = [e for e in results if e.service == options.service]
+    if options.result:
+        results = [e for e in results if e.result == options.result]
+    if options.offset:
+        results = results[options.offset:]
+    if options.limit:
+        results = results[: options.limit]
+
+    return results
+
+
+def log_action(
+    token_id: str,
+    action: str,
+    service: str,
+    result: str,
+    store: AuditStore | None = None,
+    **details: str | int | float | bool | None,
+) -> None:
+    """Log an action against a token."""
+    if store is None:
+        raise ValueError("audit store is required")
+
+    entry = AuditEntry(
+        token_id=token_id,
+        timestamp=datetime.now(timezone.utc),
+        action=action,
+        service=service,
+        result=result,
+        details=details if details else None,
+    )
+    store.append(entry)
+
+
+def get_audit_trail(
+    token_id: str,
+    options: AuditQueryOptions | None = None,
+    store: AuditStore | None = None,
+) -> list[AuditEntry]:
+    """Get the audit trail for a token."""
+    if store is None:
+        raise ValueError("audit store is required")
+    return store.query(token_id, options)
+
+
+def get_audit_trail_by_service(
+    service: str,
+    options: AuditQueryOptions | None = None,
+    store: AuditStore | None = None,
+) -> list[AuditEntry]:
+    """Get the audit trail for a service across all tokens."""
+    if store is None:
+        raise ValueError("audit store is required")
+    return store.query_by_service(service, options)

apoa-0.1.0/apoa/authorization.py

@@ -0,0 +1,122 @@
+"""Full authorization flow: revocation + scope + constraints + rules."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from .scope import check_scope
+from .types import (
+    APOAToken,
+    AuditEntry,
+    AuthorizationResult,
+    RuleViolation,
+)
+
+
+def authorize(
+    token: APOAToken,
+    service: str,
+    action: str,
+    revocation_store: Any | None = None,
+    audit_store: Any | None = None,
+) -> AuthorizationResult:
+    """One-stop authorization check: revocation + scope + constraints + rules.
+
+    Enforcement order:
+    1. Check revocation (is the token still alive?)
+    2. Check scope (is the action in the authorized scope set?)
+    3. Check constraints (action segment vs constraint key set to false)
+    4. Check hard rules (deny if rule key appears in action)
+    5. Check soft rules (log violation + invoke callback + continue)
+    """
+    # 1. Check revocation
+    if revocation_store is not None:
+        record = revocation_store.check(token.jti)
+        if record:
+            return AuthorizationResult(
+                authorized=False,
+                reason="token has been revoked",
+                checks={"revoked": True},
+            )
+
+    # 2. Check scope
+    scope_result = check_scope(token, service, action)
+    if not scope_result.allowed:
+        return AuthorizationResult(
+            authorized=False,
+            reason=scope_result.reason,
+            checks={"revoked": False, "scope_allowed": False},
+        )
+
+    # 3. Check constraints
+    service_auth = next((s for s in token.definition.services if s.service == service), None)
+    if service_auth and service_auth.constraints:
+        action_segments = action.split(":")
+        for key, value in service_auth.constraints.items():
+            if value is False and key in action_segments:
+                return AuthorizationResult(
+                    authorized=False,
+                    reason=f"constraint '{key}' is set to false",
+                    checks={"revoked": False, "scope_allowed": True, "constraints_passed": False},
+                )
+
+    # 4 & 5. Check rules
+    rules = token.definition.rules
+    violations: list[RuleViolation] = []
+
+    if rules:
+        # 4. Hard rules
+        for rule in rules:
+            if rule.enforcement == "hard":
+                rule_key = rule.id[3:] if rule.id.startswith("no-") else rule.id
+                if rule_key.lower() in action.lower():
+                    return AuthorizationResult(
+                        authorized=False,
+                        reason=f"hard rule '{rule.id}' violated",
+                        checks={
+                            "revoked": False,
+                            "scope_allowed": True,
+                            "constraints_passed": True,
+                            "rules_passed": False,
+                        },
+                    )
+
+        # 5. Soft rules
+        for rule in rules:
+            if rule.enforcement == "soft":
+                violation = RuleViolation(
+                    rule_id=rule.id,
+                    token_id=token.jti,
+                    action=action,
+                    service=service,
+                    timestamp=datetime.now(timezone.utc),
+                    details=rule.description,
+                )
+                violations.append(violation)
+
+                # Log to audit store if available
+                if audit_store is not None:
+                    audit_store.append(AuditEntry(
+                        token_id=token.jti,
+                        timestamp=violation.timestamp,
+                        action=action,
+                        service=service,
+                        result="escalated",
+                        details={"ruleId": rule.id, "ruleDescription": rule.description},
+                    ))
+
+                # Invoke on_violation callback if provided
+                if rule.on_violation:
+                    rule.on_violation(violation)
+
+    return AuthorizationResult(
+        authorized=True,
+        checks={
+            "revoked": False,
+            "scope_allowed": True,
+            "constraints_passed": True,
+            "rules_passed": True,
+        },
+        violations=violations if violations else None,
+    )

apoa-0.1.0/apoa/client.py

@@ -0,0 +1,131 @@
+"""APOAClient -- configured facade that wires up stores and keys."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .audit import MemoryAuditStore, get_audit_trail, get_audit_trail_by_service, log_action
+from .authorization import authorize
+from .constraints import check_constraint
+from .crypto import generate_key_pair
+from .delegation import delegate, verify_chain
+from .revocation import (
+    MemoryRevocationStore,
+    cascade_revoke,
+    is_revoked,
+    revoke,
+)
+from .scope import check_scope
+from .token import create_token, parse_definition, validate_token
+from .types import (
+    APOADefinition,
+    APOAToken,
+    AuditEntry,
+    AuditQueryOptions,
+    AuthorizationResult,
+    ChainVerificationResult,
+    DelegationDefinition,
+    RevocationRecord,
+    ScopeCheckResult,
+    SigningOptions,
+    ValidationOptions,
+    ValidationResult,
+)
+
+
+class APOAClient:
+    """Configured APOA client with wired-up stores and default signing options."""
+
+    def __init__(
+        self,
+        revocation_store: Any | None = None,
+        audit_store: Any | None = None,
+        key_resolver: Any | None = None,
+        default_private_key: Any | None = None,
+        default_algorithm: str = "EdDSA",
+    ) -> None:
+        self._revocation_store = revocation_store or MemoryRevocationStore()
+        self._audit_store = audit_store or MemoryAuditStore()
+        self._key_resolver = key_resolver
+        self._default_private_key = default_private_key
+        self._default_algorithm = default_algorithm
+
+    def _signing_options(self, options: SigningOptions | None = None) -> SigningOptions:
+        if options:
+            return options
+        if self._default_private_key is None:
+            raise ValueError("No signing options provided and no default_private_key configured")
+        return SigningOptions(private_key=self._default_private_key, algorithm=self._default_algorithm)
+
+    def create_token(self, definition: APOADefinition, options: SigningOptions | None = None) -> APOAToken:
+        return create_token(definition, self._signing_options(options))
+
+    def validate_token(self, token: str | APOAToken, options: ValidationOptions | None = None) -> ValidationResult:
+        opts = options or ValidationOptions()
+        # Wire up defaults
+        if opts.key_resolver is None and self._key_resolver is not None:
+            opts.key_resolver = self._key_resolver
+        if opts.revocation_store is None:
+            opts.revocation_store = self._revocation_store
+        if not opts.check_revocation:
+            opts.check_revocation = True
+        return validate_token(token, opts)
+
+    def check_scope(self, token: APOAToken, service: str, action: str) -> ScopeCheckResult:
+        return check_scope(token, service, action)
+
+    def check_constraint(self, token: APOAToken, service: str, constraint: str) -> ScopeCheckResult:
+        return check_constraint(token, service, constraint)
+
+    def authorize(self, token: APOAToken, service: str, action: str) -> AuthorizationResult:
+        return authorize(token, service, action, self._revocation_store, self._audit_store)
+
+    def delegate(self, parent_token: APOAToken, child_def: DelegationDefinition, options: SigningOptions | None = None) -> APOAToken:
+        return delegate(parent_token, child_def, self._signing_options(options))
+
+    def verify_chain(self, chain: list[APOAToken]) -> ChainVerificationResult:
+        return verify_chain(chain, self._revocation_store)
+
+    def revoke(self, token_id: str, revoked_by: str, reason: str | None = None) -> RevocationRecord:
+        return revoke(token_id, revoked_by, reason, self._revocation_store)
+
+    def is_revoked(self, token_id: str) -> bool:
+        return is_revoked(token_id, self._revocation_store)
+
+    def cascade_revoke(self, parent_token_id: str, child_token_ids: list[str], revoked_by: str, reason: str | None = None) -> RevocationRecord:
+        return cascade_revoke(parent_token_id, child_token_ids, revoked_by, reason, self._revocation_store)
+
+    def log_action(self, token_id: str, action: str, service: str, result: str, **details: str | int | float | bool | None) -> None:
+        log_action(token_id, action, service, result, self._audit_store, **details)
+
+    def get_audit_trail(self, token_id: str, options: AuditQueryOptions | None = None) -> list[AuditEntry]:
+        return get_audit_trail(token_id, options, self._audit_store)
+
+    def get_audit_trail_by_service(self, service: str, options: AuditQueryOptions | None = None) -> list[AuditEntry]:
+        return get_audit_trail_by_service(service, options, self._audit_store)
+
+    def generate_key_pair(self, algorithm: str | None = None) -> tuple:
+        return generate_key_pair(algorithm or self._default_algorithm)
+
+    def parse_definition(self, input_str: str, format: str = "json") -> APOADefinition:
+        return parse_definition(input_str, format)
+
+
+def create_client(
+    revocation_store: Any | None = None,
+    audit_store: Any | None = None,
+    key_resolver: Any | None = None,
+    default_private_key: Any | None = None,
+    default_algorithm: str = "EdDSA",
+) -> APOAClient:
+    """Create a configured APOA client.
+
+    Defaults to MemoryRevocationStore + MemoryAuditStore for zero-config dev/testing.
+    """
+    return APOAClient(
+        revocation_store=revocation_store,
+        audit_store=audit_store,
+        key_resolver=key_resolver,
+        default_private_key=default_private_key,
+        default_algorithm=default_algorithm,
+    )