agentauthlayer 0.1.0__py3-none-any.whl

agent_auth/exceptions.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+
+class AgentAuthError(Exception):
+    """Base error for the agent_auth SDK."""
+
+
+class AuthServiceError(AgentAuthError):
+    """Raised when the remote Agent Auth service returns an error."""
+
+
+class InvalidTokenError(AuthServiceError):
+    """Raised when a token is invalid or cannot be verified."""
+
+
+class RevokedTokenError(AuthServiceError):
+    """Raised when a token has been revoked or is inactive."""
+
+
+class PermissionDeniedError(AuthServiceError):
+    """Raised when a caller does not have permission to perform an action."""
+
+
+class AgentNotFoundError(AuthServiceError):
+    """Raised when the requested agent does not exist."""
+
+
+class DuplicateAgentError(AgentAuthError):
+    pass
+
+
+class DuplicateUserError(AgentAuthError):
+    pass
+
+
+class InvalidCredentialsError(AgentAuthError):
+    pass
+
+
+class InvalidResetTokenError(AgentAuthError):
+    pass
+
+
+class ScopeError(AgentAuthError):
+    def __init__(self, required: str, granted: list[str]):
+        self.required = required
+        self.granted = granted
+        super().__init__(f"Missing required scope '{required}'. Granted scopes: {granted}")
+
+
+class TokenExpiredError(AgentAuthError):
+    pass
+
+
+class TokenInvalidError(AgentAuthError):
+    pass
+
+
+class TokenMissingError(AgentAuthError):
+    pass
+
+
+class TokenRevokedError(AgentAuthError):
+    pass
+
+
+class TokenTypeMismatchError(AgentAuthError):
+    pass
+
+
+class UserNotFoundError(AgentAuthError):
+    pass

agent_auth/models.py

@@ -0,0 +1,72 @@
+"""agent_auth data models — lightweight, reusable shared models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass(frozen=True, slots=True)
+class Agent:
+    agent_id: str
+    scopes: list[str] = field(default_factory=list)
+    metadata: dict = field(default_factory=dict)
+    name: str | None = None
+    owner: str | None = None
+    role: str | None = None
+    status: str = "active"
+    created_at: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class User:
+    id: str
+    email: str
+    name: str | None = None
+    role: str = "user"
+    created_at: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TokenClaims:
+    agent_id: str
+    jti: str
+    scopes: list[str]
+    issued_at: datetime
+    expires_at: datetime
+    raw: dict = field(default_factory=dict)
+    token_type: str = "access"
+
+
+@dataclass(frozen=True, slots=True)
+class UserClaims:
+    user_id: str
+    email: str
+    role: str
+    jti: str
+    issued_at: datetime
+    expires_at: datetime
+    raw: dict = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class TokenRecord:
+    jti: str
+    principal_id: str
+    principal_type: str
+    scopes: list[str]
+    expires_at: datetime
+    status: str = 'active'
+    created_at: datetime = field(default_factory=utc_now)
+
+    @property
+    def subject_id(self) -> str:
+        return self.principal_id
+
+    @property
+    def subject_type(self) -> str:
+        return self.principal_type

agent_auth/policy.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any, Callable
+
+from agent_auth.delegation import DelegationGrant
+from agent_auth.exceptions import ScopeError
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionDefinition:
+    action: str
+    description: str = ''
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyStatement:
+    effect: str
+    actions: list[str]
+    resources: list[str] = field(default_factory=lambda: ['*'])
+    conditions: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            'effect': self.effect,
+            'actions': self.actions,
+            'resources': self.resources,
+            'conditions': self.conditions,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> PolicyStatement:
+        return cls(
+            effect=data.get('effect', 'DENY'),
+            actions=data.get('actions', []),
+            resources=data.get('resources', ['*']),
+            conditions=data.get('conditions', {}),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RoleDefinition:
+    name: str
+    statements: list[PolicyStatement] = field(default_factory=list)
+    description: str = ''
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyRequest:
+    principal_id: str
+    action: str
+    resource: str | None = None
+    granted_scopes: list[str] = field(default_factory=list)
+    role: str | None = None
+    context: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyDecision:
+    allowed: bool
+    reason: str
+    matched_role: str | None = None
+    matched_permission: str | None = None
+    resource: str | None = None
+    delegation_grant_id: str | None = None
+
+
+DEFAULT_ROLES: dict[str, RoleDefinition] = {
+    'admin': RoleDefinition(
+        name='admin',
+        description='Full access to all systems',
+        statements=[PolicyStatement(effect='ALLOW', actions=['*'], resources=['*'])],
+    ),
+    'research_agent': RoleDefinition(
+        name='research_agent',
+        description='Can research and read docs, with restricted LLM usage',
+        statements=[
+            PolicyStatement(effect='ALLOW', actions=['docs.read', 'tool.search_web'], resources=['*']),
+            PolicyStatement(
+                effect='ALLOW',
+                actions=['tool.call_llm'],
+                resources=['model/*'],
+                conditions={'StringEquals': {'environment': 'approved'}},
+            ),
+        ],
+    ),
+    'ops_agent': RoleDefinition(
+        name='ops_agent',
+        description='Can run workflows and read audits',
+        statements=[PolicyStatement(effect='ALLOW', actions=['workflow.run', 'audit.read'], resources=['*'])],
+    ),
+}
+
+SCOPE_TO_ACTIONS: dict[str, list[str]] = {
+    'admin_agents': ['agent.create', 'agent.update_scopes'],
+    'admin_tokens': ['token.revoke'],
+    'read_audit': ['audit.read'],
+    'call_llm': ['tool.call_llm'],
+    'run_graph': ['workflow.run'],
+    'search_web': ['tool.search_web'],
+    'send_email': ['tool.send_email'],
+    'read_only': ['agent.read'],
+}
+
+
+def check_scope(granted: list[str], required: str) -> None:
+    if '*' in granted:
+        return
+    if required not in granted:
+        raise ScopeError(required, granted)
+
+
+def check_scopes(granted: list[str], required: list[str]) -> None:
+    for scope in required:
+        check_scope(granted, scope)
+
+
+def _match_string(pattern: str, target: str) -> bool:
+    if pattern == '*':
+        return True
+    return fnmatch.fnmatch(target, pattern)
+
+
+class PolicyEvaluator:
+    def __init__(
+        self,
+        roles: dict[str, RoleDefinition] | None = None,
+        scope_to_actions: dict[str, list[str]] | None = None,
+        active_delegations: list[DelegationGrant] | None = None,
+    ) -> None:
+        self._roles = roles if roles is not None else DEFAULT_ROLES
+        self._scope_to_actions = scope_to_actions or SCOPE_TO_ACTIONS
+        self._active_delegations = active_delegations or []
+
+        self._permissions = {}
+        for role in self._roles.values():
+            for stmt in role.statements:
+                for action in stmt.actions:
+                    if action != '*':
+                        self._permissions.setdefault(action, PermissionDefinition(action=action))
+        for actions in self._scope_to_actions.values():
+            for action in actions:
+                self._permissions.setdefault(action, PermissionDefinition(action=action))
+
+    def _check_delegations(self, request: PolicyRequest) -> PolicyDecision | None:
+        from datetime import datetime, timezone
+
+        now = datetime.now(timezone.utc)
+        for grant in self._active_delegations:
+            if grant.delegatee_id != request.principal_id:
+                continue
+            if grant.expires_at and grant.expires_at < now:
+                continue
+            if grant.action != request.action:
+                continue
+            if grant.resource and request.resource and not request.resource.startswith(grant.resource):
+                continue
+            context_match = True
+            for k, v in grant.context.items():
+                if request.context.get(k) != v:
+                    context_match = False
+                    break
+            if context_match:
+                return PolicyDecision(
+                    allowed=True,
+                    reason='allowed_by_delegation',
+                    matched_role=None,
+                    matched_permission=request.action,
+                    resource=request.resource,
+                    delegation_grant_id=grant.grant_id,
+                )
+        return None
+
+    def _evaluate_conditions(self, conditions: dict[str, dict[str, Any]], context: dict[str, str]) -> bool:
+        if not conditions:
+            return True
+        for operator, kv in conditions.items():
+            if operator == 'StringEquals':
+                for k, v in kv.items():
+                    if context.get(k) != v:
+                        return False
+            elif operator == 'StringNotEquals':
+                for k, v in kv.items():
+                    if context.get(k) == v:
+                        return False
+        return True
+
+    def _statement_matches(self, stmt: PolicyStatement, request: PolicyRequest) -> bool:
+        if not any(_match_string(act, request.action) for act in stmt.actions):
+            return False
+        req_res = request.resource or '*'
+        if not any(_match_string(res, req_res) for res in stmt.resources):
+            return False
+        if not self._evaluate_conditions(stmt.conditions, request.context):
+            return False
+        return True
+
+    def _scope_allows(self, request: PolicyRequest) -> bool:
+        allowed_actions: set[str] = set()
+        for scope in request.granted_scopes:
+            allowed_actions.update(self._scope_to_actions.get(scope, []))
+        return any(_match_string(action, request.action) for action in allowed_actions)
+
+    def evaluate(self, request: PolicyRequest) -> PolicyDecision:
+        delegation_decision = self._check_delegations(request)
+        if delegation_decision:
+            return delegation_decision
+
+        role_name = request.role
+        role_def = self._roles.get(role_name)
+        if not role_def and role_name in DEFAULT_ROLES:
+            role_def = DEFAULT_ROLES[role_name]
+
+        if not role_def:
+            if self._scope_allows(request):
+                return PolicyDecision(
+                    allowed=True,
+                    reason='allowed_by_scope',
+                    matched_role=request.role,
+                    matched_permission=request.action,
+                    resource=request.resource,
+                )
+            return PolicyDecision(
+                allowed=False,
+                reason='missing_permission',
+                matched_role=request.role,
+                resource=request.resource,
+            )
+
+        for stmt in role_def.statements:
+            if stmt.effect == 'DENY' and self._statement_matches(stmt, request):
+                return PolicyDecision(
+                    allowed=False,
+                    reason='explicit_deny',
+                    matched_role=request.role,
+                    matched_permission=request.action,
+                    resource=request.resource,
+                )
+
+        for stmt in role_def.statements:
+            if stmt.effect == 'ALLOW' and self._statement_matches(stmt, request):
+                return PolicyDecision(
+                    allowed=True,
+                    reason='allowed_by_policy',
+                    matched_role=request.role,
+                    matched_permission=request.action,
+                    resource=request.resource,
+                )
+
+        if self._scope_allows(request):
+            return PolicyDecision(
+                allowed=True,
+                reason='allowed_by_scope',
+                matched_role=request.role,
+                matched_permission=request.action,
+                resource=request.resource,
+            )
+
+        return PolicyDecision(
+            allowed=False,
+            reason='implicit_deny',
+            matched_role=request.role,
+            resource=request.resource,
+        )
+
+
+def require_permission(action: str, resource: str | None = None):
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            agent_id = kwargs.get('agent_id') or (args[0] if args else None)
+            role = kwargs.get('role')
+            context = kwargs.get('context', {}) or {}
+            granted_scopes = kwargs.get('granted_scopes', []) or []
+            resource_value = kwargs.get('resource') or resource or '*'
+
+            evaluator = PolicyEvaluator()
+            decision = evaluator.evaluate(
+                PolicyRequest(
+                    principal_id=agent_id or 'unknown',
+                    action=action,
+                    resource=resource_value,
+                    granted_scopes=granted_scopes,
+                    role=role,
+                    context=context,
+                )
+            )
+            if not decision.allowed:
+                raise PermissionError(f'Access Denied: {decision.reason}')
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

agent_auth/policy_service.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Protocol
+
+from agent_auth.delegation import DelegationGrant
+from agent_auth.policy import DEFAULT_ROLES, PermissionDefinition, PolicyDecision, PolicyEvaluator, PolicyRequest, PolicyStatement, RoleDefinition
+from agent_auth.principals import Principal, user_scopes_for_role
+
+
+class RoleStore(Protocol):
+    def save(self, role: RoleDefinition) -> RoleDefinition:
+        ...
+
+    def get(self, name: str) -> RoleDefinition | None:
+        ...
+
+    def list_roles(self) -> list[RoleDefinition]:
+        ...
+
+
+class PermissionStore(Protocol):
+    def save(self, permission: PermissionDefinition) -> PermissionDefinition:
+        ...
+
+    def list_permissions(self) -> list[PermissionDefinition]:
+        ...
+
+
+class DelegationStore(Protocol):
+    def save(self, grant: DelegationGrant) -> DelegationGrant:
+        ...
+
+    def list_for_delegatee(self, delegatee_id: str) -> list[DelegationGrant]:
+        ...
+
+
+class CorePolicyService:
+    """Core policy, permission, and delegation orchestration."""
+
+    def __init__(
+        self,
+        role_store: RoleStore,
+        delegation_store: DelegationStore,
+        permission_store: PermissionStore,
+        constraint_store=None,
+    ) -> None:
+        self.role_store = role_store
+        self.delegation_store = delegation_store
+        self.permission_store = permission_store
+        self.constraint_store = constraint_store
+
+    def list_roles(self, include_defaults: bool = False) -> list[RoleDefinition]:
+        persisted_roles = self.role_store.list_roles()
+        if not include_defaults:
+            return persisted_roles
+        custom_roles = {role.name: role for role in persisted_roles}
+        return list({**DEFAULT_ROLES, **custom_roles}.values())
+
+    def get_effective_roles(self) -> dict[str, RoleDefinition]:
+        persisted_roles = {role.name: role for role in self.role_store.list_roles()}
+        return {**DEFAULT_ROLES, **persisted_roles}
+
+    def upsert_role(self, role: RoleDefinition) -> RoleDefinition:
+        return self.role_store.save(role)
+
+    def build_role(self, name: str, statements: list[PolicyStatement], description: str = '', permissions: list[str] | None = None) -> RoleDefinition:
+        effective_statements = statements
+        if permissions and not effective_statements:
+            effective_statements = [PolicyStatement(effect='ALLOW', actions=permissions, resources=['*'])]
+        return RoleDefinition(name=name, statements=effective_statements, description=description)
+
+    def list_permissions(self, include_defaults: bool = True) -> list[PermissionDefinition]:
+        seen: dict[str, PermissionDefinition] = {
+            permission.action: permission for permission in self.permission_store.list_permissions()
+        }
+        if include_defaults:
+            for role in self.get_effective_roles().values():
+                for statement in role.statements:
+                    for action in statement.actions:
+                        if action != '*' and action not in seen:
+                            seen[action] = PermissionDefinition(action=action, description='')
+        return list(seen.values())
+
+    def upsert_permission(self, permission: PermissionDefinition) -> PermissionDefinition:
+        return self.permission_store.save(permission)
+
+    def sync_permissions(self, permissions: list[PermissionDefinition]) -> int:
+        for permission in permissions:
+            self.upsert_permission(permission)
+        return len(permissions)
+
+    def grant_delegation(self, grant: DelegationGrant) -> DelegationGrant:
+        return self.delegation_store.save(grant)
+
+    def list_delegations_for_delegatee(self, delegatee_id: str) -> list[DelegationGrant]:
+        return self.delegation_store.list_for_delegatee(delegatee_id)
+
+    def evaluate(self, request: PolicyRequest) -> PolicyDecision:
+        evaluator = PolicyEvaluator(
+            roles=self.get_effective_roles(),
+            active_delegations=self.delegation_store.list_for_delegatee(request.principal_id),
+        )
+        return evaluator.evaluate(request)
+
+    def build_request(
+        self,
+        *,
+        principal_id: str,
+        action: str,
+        resource: str | None = None,
+        granted_scopes: list[str] | None = None,
+        role: str | None = None,
+        context: dict[str, str] | None = None,
+    ) -> PolicyRequest:
+        return PolicyRequest(
+            principal_id=principal_id,
+            action=action,
+            resource=resource,
+            granted_scopes=granted_scopes or [],
+            role=role,
+            context=context or {},
+        )
+
+    def grant_delegation_if_allowed(
+        self,
+        *,
+        delegator: Principal,
+        grant_id: str,
+        delegatee_id: str,
+        action: str,
+        resource: str | None = None,
+        expires_in_seconds: int | None = None,
+        context: dict[str, str] | None = None,
+    ) -> tuple[DelegationGrant | None, PolicyDecision]:
+        delegator_role = delegator.role
+        if delegator_role is None and 'admin_agents' in delegator.scopes:
+            delegator_role = 'admin'
+        decision = self.evaluate(
+            self.build_request(
+                principal_id=delegator.principal_id,
+                action=action,
+                resource=resource,
+                granted_scopes=delegator.scopes,
+                role=delegator_role,
+                context=context or {},
+            )
+        )
+        if not decision.allowed:
+            return None, decision
+        expires_at = None
+        if expires_in_seconds:
+            expires_at = datetime.now(timezone.utc) + timedelta(seconds=expires_in_seconds)
+        grant = DelegationGrant(
+            grant_id=grant_id,
+            delegator_id=delegator.principal_id,
+            delegatee_id=delegatee_id,
+            action=action,
+            resource=resource,
+            expires_at=expires_at,
+            context=context or {},
+        )
+        return self.grant_delegation(grant), decision
+
+    def effective_access_for_user(self, *, user_id: str, email: str, role: str):
+        scopes = user_scopes_for_role(role)
+        return {
+            'user_id': user_id,
+            'email': email,
+            'role': role,
+            'scopes': scopes,
+            'can_manage_users': 'admin_users' in scopes,
+            'can_manage_agents': 'admin_agents' in scopes,
+            'can_manage_tokens': 'admin_tokens' in scopes,
+            'can_read_audit': 'read_audit' in scopes,
+        }

agent_auth/principals.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+PrincipalType = Literal['user', 'agent', 'system']
+
+
+@dataclass(slots=True)
+class Principal:
+    principal_id: str
+    principal_type: PrincipalType
+    role: str | None = None
+    scopes: list[str] = field(default_factory=list)
+    email: str | None = None
+    owner: str | None = None
+    status: str | None = None
+
+
+@dataclass(slots=True)
+class UserPrincipal(Principal):
+    principal_type: PrincipalType = 'user'
+
+
+@dataclass(slots=True)
+class AgentPrincipal(Principal):
+    principal_type: PrincipalType = 'agent'
+
+
+@dataclass(slots=True)
+class SystemPrincipal(Principal):
+    principal_type: PrincipalType = 'system'
+
+
+DEFAULT_USER_ROLE_SCOPES: dict[str, list[str]] = {
+    'super_admin': ['admin_users', 'admin_agents', 'admin_tokens', 'read_audit'],
+    'admin': ['admin_users', 'admin_agents', 'admin_tokens', 'read_audit'],
+    'auditor': ['read_audit'],
+    'viewer': ['read_audit'],
+}
+
+
+def user_scopes_for_role(role: str) -> list[str]:
+    return list(DEFAULT_USER_ROLE_SCOPES.get(role, []))