agentauthlayer 0.1.9__tar.gz → 0.1.11__tar.gz

{agentauthlayer-0.1.9 → agentauthlayer-0.1.11}/MANIFEST.in

@@ -1,2 +1 @@
 recursive-include agent_auth/web_dist *
-include agent_auth_definitive_guide.pdf

{agentauthlayer-0.1.9 → agentauthlayer-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentauthlayer
-Version: 0.1.9
+Version: 0.1.11
 Summary: Library-first authentication and authorization SDK for AI agents
 Author: Vaibhav Ahluwalia
 License: MIT
@@ -32,6 +32,68 @@ Requires-Dist: email-validator
 
 Unified SDK and local control plane package for Agent Auth.
 
+## Token-first developer flow
+
+You can now create project-scoped tokens from:
+- the Project Settings page in the UI
+- the Tokens page in the UI
+- the CLI with `agentauth token create`
+
+These tokens support one visible token model with richer internal semantics:
+- `purpose=sync` for registration and sync flows
+- `purpose=runtime` for runtime execution flows
+- `purpose=automation` for service or CI style automation
+- optional `agent_id` binding for runtime-oriented tokens
+
+## Runtime binding
+
+Runtime authorization now enforces stronger execution binding checks for project-scoped flows:
+- project scope mismatches are denied before policy evaluation
+- agent/principal mismatches are denied before policy evaluation
+- execution context automatically carries project, agent, principal, and token-purpose context into authorization checks
+- runtime-bound tokens now carry first-class `project_id`, `agent_id`, and `purpose` fields, with scope-based fallback for older tokens
+
+Use the resulting token in code directly:
+
+```python
+from agent_auth.client import AuthAPIClient
+
+client = AuthAPIClient(
+    base_url="http://127.0.0.1:8002",
+    token="YOUR_PROJECT_TOKEN",
+)
+```
+
+Or store it locally for CLI + SDK reuse:
+
+```bash
+agentauth login --base-url http://127.0.0.1:8002 --token YOUR_PROJECT_TOKEN --email admin@agentauth.dev
+```
+
+### Create a bound runtime token from the CLI
+
+```bash
+agentauth token create \
+  --project ai-platform \
+  --name research-runtime-token \
+  --purpose runtime \
+  --agent-id research-agent-01 \
+  --scope docs.read
+```
+
+Then use it directly in code:
+
+```python
+from agent_auth import AuthAPIClient
+
+client = AuthAPIClient(token="YOUR_RUNTIME_TOKEN")
+ctx = client.execution_context()
+
+print(ctx.project_id)
+print(ctx.agent_id)
+print(ctx.context.get("token_purpose"))
+```
+
 `agentauthlayer` helps you:
 - start a local Agent Auth backend and UI with one command
 - authenticate once and reuse local credentials

{agentauthlayer-0.1.9 → agentauthlayer-0.1.11}/README.md

@@ -2,6 +2,68 @@
 
 Unified SDK and local control plane package for Agent Auth.
 
+## Token-first developer flow
+
+You can now create project-scoped tokens from:
+- the Project Settings page in the UI
+- the Tokens page in the UI
+- the CLI with `agentauth token create`
+
+These tokens support one visible token model with richer internal semantics:
+- `purpose=sync` for registration and sync flows
+- `purpose=runtime` for runtime execution flows
+- `purpose=automation` for service or CI style automation
+- optional `agent_id` binding for runtime-oriented tokens
+
+## Runtime binding
+
+Runtime authorization now enforces stronger execution binding checks for project-scoped flows:
+- project scope mismatches are denied before policy evaluation
+- agent/principal mismatches are denied before policy evaluation
+- execution context automatically carries project, agent, principal, and token-purpose context into authorization checks
+- runtime-bound tokens now carry first-class `project_id`, `agent_id`, and `purpose` fields, with scope-based fallback for older tokens
+
+Use the resulting token in code directly:
+
+```python
+from agent_auth.client import AuthAPIClient
+
+client = AuthAPIClient(
+    base_url="http://127.0.0.1:8002",
+    token="YOUR_PROJECT_TOKEN",
+)
+```
+
+Or store it locally for CLI + SDK reuse:
+
+```bash
+agentauth login --base-url http://127.0.0.1:8002 --token YOUR_PROJECT_TOKEN --email admin@agentauth.dev
+```
+
+### Create a bound runtime token from the CLI
+
+```bash
+agentauth token create \
+  --project ai-platform \
+  --name research-runtime-token \
+  --purpose runtime \
+  --agent-id research-agent-01 \
+  --scope docs.read
+```
+
+Then use it directly in code:
+
+```python
+from agent_auth import AuthAPIClient
+
+client = AuthAPIClient(token="YOUR_RUNTIME_TOKEN")
+ctx = client.execution_context()
+
+print(ctx.project_id)
+print(ctx.agent_id)
+print(ctx.context.get("token_purpose"))
+```
+
 `agentauthlayer` helps you:
 - start a local Agent Auth backend and UI with one command
 - authenticate once and reuse local credentials

{agentauthlayer-0.1.9 → agentauthlayer-0.1.11}/agent_auth/__init__.py

@@ -2,7 +2,7 @@
 
 from agent_auth.auth import principal_fields, principal_from_agent, principal_from_user
 from agent_auth.client import AuthAPIClient
-from agent_auth.context import AuthContext
+from agent_auth.context import AuthContext, ExecutionContext, execution_context_from_args, execution_context_from_token_payload
 from agent_auth.delegation import DelegationGrant
 from agent_auth.exceptions import (
     AgentAuthError,
@@ -30,6 +30,7 @@ __all__ = [
     "AgentPrincipal",
     "AuthAPIClient",
     "AuthContext",
+    "ExecutionContext",
     "AuthServiceError",
     "DelegationGrant",
     "InvalidTokenError",
@@ -50,6 +51,8 @@ __all__ = [
     "clear_registries",
     "list_registered_agents",
     "list_registered_tools",
+    "execution_context_from_args",
+    "execution_context_from_token_payload",
     "principal_fields",
     "principal_from_agent",
     "principal_from_user",

{agentauthlayer-0.1.9 → agentauthlayer-0.1.11}/agent_auth/cli.py

@@ -137,28 +137,58 @@ def sync_command(args) -> int:
     tools = list_registered_tools()
     agents = list_registered_agents()
 
-    if tools:
-        client.sync_tools([
-            {'action': tool.action, 'description': tool.description}
-            for tool in tools
-        ])
+    existing_permissions = {permission['action']: permission for permission in client.list_permissions()}
+    tool_payload = [{'action': tool.action, 'description': tool.description} for tool in tools]
+    tools_to_sync = [tool for tool in tool_payload if existing_permissions.get(tool['action'], {}).get('description') != tool['description']]
+    if tools_to_sync:
+        client.sync_tools(tools_to_sync)
 
-    created_agents = []
+    agent_results = []
     for agent in agents:
-        created_agents.append(client.create_agent(
-            agent_id=agent.agent_id,
-            name=agent.name,
-            owner=agent.owner,
-            role=agent.role,
-            scopes=agent.scopes,
-            project_id=args.project or agent.project_id,
-        ))
+        target_project = args.project or agent.project_id
+        try:
+            existing = client.get_agent(agent.agent_id)
+        except AgentNotFoundError:
+            existing = None
+
+        desired = {
+            'name': agent.name,
+            'role': agent.role,
+            'scopes': list(agent.scopes),
+            'project_id': target_project,
+        }
+
+        if existing is None:
+            created = client.create_agent(
+                agent_id=agent.agent_id,
+                name=agent.name,
+                owner=agent.owner,
+                role=agent.role,
+                scopes=agent.scopes,
+                project_id=target_project,
+            )
+            agent_results.append({'agent_id': created['agent_id'], 'status': 'created'})
+            continue
+
+        changed_fields = {}
+        for field in ['name', 'role', 'project_id', 'scopes']:
+            if existing.get(field) != desired[field]:
+                changed_fields[field] = desired[field]
+
+        if changed_fields:
+            updated = client.update_agent(agent.agent_id, **changed_fields)
+            agent_results.append({'agent_id': updated['agent_id'], 'status': 'updated', 'changed_fields': sorted(changed_fields.keys())})
+        else:
+            agent_results.append({'agent_id': agent.agent_id, 'status': 'unchanged'})
 
     print(json.dumps({
         'module': args.module,
         'project': args.project,
-        'synced_tools': [tool.action for tool in tools],
-        'synced_agents': [agent['agent_id'] for agent in created_agents],
+        'tools': {
+            'added_or_updated': [tool['action'] for tool in tools_to_sync],
+            'unchanged': [tool.action for tool in tools if tool.action not in {item['action'] for item in tools_to_sync}],
+        },
+        'agents': agent_results,
     }, indent=2))
     return 0
 
@@ -184,6 +214,33 @@ def project_create_command(args) -> int:
     return 0
 
 
+def token_create_command(args) -> int:
+    client = AuthAPIClient()
+    token = client.create_project_token(
+        args.project,
+        args.name,
+        args.scopes or [],
+        purpose=args.purpose,
+        agent_id=args.agent_id,
+    )
+    print(json.dumps(token, indent=2))
+    return 0
+
+
+def token_list_command(args) -> int:
+    client = AuthAPIClient()
+    tokens = client.list_tokens(args.subject_type)
+    print(json.dumps(tokens, indent=2))
+    return 0
+
+
+def token_revoke_command(args) -> int:
+    client = AuthAPIClient()
+    result = client.revoke_token_by_jti(args.jti)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
 def ui_command(args) -> int:
     creds = load_credentials() or {}
     base_url = (args.base_url or creds.get('base_url') or DEFAULT_BASE_URL).rstrip('/')
@@ -266,6 +323,25 @@ def main():
     project_create_parser.add_argument('--description')
     project_create_parser.set_defaults(func=project_create_command)
 
+    token_parser = subparsers.add_parser('token', help='Manage project tokens from the CLI')
+    token_subparsers = token_parser.add_subparsers(dest='token_command')
+
+    token_create_parser = token_subparsers.add_parser('create', help='Create a project token')
+    token_create_parser.add_argument('--project', required=True)
+    token_create_parser.add_argument('--name', required=True)
+    token_create_parser.add_argument('--scope', dest='scopes', action='append', help='Scope to include. Repeat for multiple scopes.')
+    token_create_parser.add_argument('--purpose', default='sync', choices=['sync', 'runtime', 'automation'], help='Intended token purpose.')
+    token_create_parser.add_argument('--agent-id', help='Optional runtime agent binding for runtime-oriented tokens.')
+    token_create_parser.set_defaults(func=token_create_command)
+
+    token_list_parser = token_subparsers.add_parser('list', help='List tokens')
+    token_list_parser.add_argument('--subject-type', choices=['user', 'agent', 'system'])
+    token_list_parser.set_defaults(func=token_list_command)
+
+    token_revoke_parser = token_subparsers.add_parser('revoke', help='Revoke a token by JTI')
+    token_revoke_parser.add_argument('--jti', required=True)
+    token_revoke_parser.set_defaults(func=token_revoke_command)
+
     delete_agent_parser = subparsers.add_parser('delete-agent', help='Delete an agent by ID')
     delete_agent_parser.add_argument('agent_id')
     delete_agent_parser.set_defaults(func=delete_agent_command)

agentauthlayer-0.1.11/agent_auth/client.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any
+
+import requests
+
+from agent_auth.context import AuthContext, ExecutionContext, execution_context_from_token_payload
+from agent_auth.credentials import load_credentials
+from agent_auth.exceptions import (
+    AgentNotFoundError,
+    AuthServiceError,
+    InvalidTokenError,
+    PermissionDeniedError,
+    RevokedTokenError,
+)
+
+
+class AuthAPIClient:
+    """Thin SDK client for talking to the Agent Auth control plane."""
+
+    def __init__(self, base_url: str | None = None, token: str | None = None, timeout: int = 30) -> None:
+        stored = load_credentials() or {}
+        self.base_url = (base_url or os.getenv("AGENT_AUTH_URL") or stored.get("base_url") or "http://127.0.0.1:8002").rstrip("/")
+        self.token = token or os.getenv("AGENT_AUTH_TOKEN") or stored.get("token")
+        self.timeout = timeout
+
+        if token:
+            self.auth_source = "explicit_token"
+        elif os.getenv("AGENT_AUTH_TOKEN"):
+            self.auth_source = "env_token"
+        elif stored.get("token"):
+            self.auth_source = "stored_credentials"
+        else:
+            self.auth_source = "none"
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def decode_token(self, token: str | None = None) -> dict[str, Any] | None:
+        raw = token or self.token
+        if not raw:
+            return None
+        try:
+            parts = raw.split('.')
+            if len(parts) != 3:
+                return None
+            payload = parts[1]
+            padding = '=' * (-len(payload) % 4)
+            decoded = base64.urlsafe_b64decode(payload + padding)
+            return json.loads(decoded.decode('utf-8'))
+        except Exception:
+            return None
+
+    def _request(self, method: str, path: str, json: dict[str, Any] | None = None) -> Any:
+        response = requests.request(
+            method,
+            f"{self.base_url}{path}",
+            json=json,
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+
+        if response.ok:
+            if not response.content:
+                return None
+            return response.json()
+
+        detail = None
+        try:
+            detail = response.json().get("detail")
+        except Exception:
+            detail = response.text or "Request failed"
+
+        if response.status_code == 401:
+            if detail and ("revoked" in detail.lower() or "inactive" in detail.lower()):
+                raise RevokedTokenError(detail)
+            raise InvalidTokenError(detail or "Invalid token")
+        if response.status_code == 403:
+            raise PermissionDeniedError(detail or "Permission denied")
+        if response.status_code == 404 and path.startswith("/agents/"):
+            raise AgentNotFoundError(detail or "Agent not found")
+        if response.status_code == 404 and path == "/agents" and detail and "Project not found" in detail:
+            raise AuthServiceError(
+                "Project not found. Create the project in the Agent Auth UI first, or update your agent's project_id to match an existing project."
+            )
+        raise AuthServiceError(detail or f"Request failed with status {response.status_code}")
+
+    def health(self) -> dict[str, Any]:
+        return self._request("GET", "/health")
+
+    def me(self) -> dict[str, Any]:
+        return self._request("GET", "/users/me")
+
+    def create_agent(self, agent_id: str, name: str, owner: str, role: str, scopes: list[str], project_id: str | None = None) -> dict[str, Any]:
+        payload = {
+            "agent_id": agent_id,
+            "name": name,
+            "owner": owner,
+            "role": role,
+            "scopes": scopes,
+        }
+        if project_id:
+            payload["project_id"] = project_id
+        return self._request("POST", "/agents", json=payload)
+
+    def update_agent(self, agent_id: str, *, name: str | None = None, role: str | None = None, scopes: list[str] | None = None, project_id: str | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if role is not None:
+            payload["role"] = role
+        if scopes is not None:
+            payload["scopes"] = scopes
+        if project_id is not None:
+            payload["project_id"] = project_id
+        return self._request("PATCH", f"/agents/{agent_id}", json=payload)
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/projects")
+
+    def create_project(self, project_id: str, name: str, description: str = "") -> dict[str, Any]:
+        return self._request(
+            "POST",
+            "/projects",
+            json={"project_id": project_id, "name": name, "description": description},
+        )
+
+    def create_project_token(
+        self,
+        project_id: str,
+        name: str,
+        scopes: list[str] | None = None,
+        *,
+        purpose: str = "sync",
+        agent_id: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "project_id": project_id,
+            "name": name,
+            "scopes": scopes or [],
+            "purpose": purpose,
+        }
+        if agent_id:
+            payload["agent_id"] = agent_id
+        return self._request("POST", "/tokens/project", json=payload)
+
+    def create_sync_token(self, project_id: str, name: str = "project-sync-token", scopes: list[str] | None = None) -> dict[str, Any]:
+        return self.create_project_token(project_id, name, scopes or ["admin_agents", "admin_tokens"], purpose="sync")
+
+    def create_runtime_token(self, project_id: str, agent_id: str, name: str = "project-runtime-token", scopes: list[str] | None = None) -> dict[str, Any]:
+        return self.create_project_token(project_id, name, scopes or ["docs.read"], purpose="runtime", agent_id=agent_id)
+
+    def create_automation_token(self, project_id: str, name: str = "project-automation-token", scopes: list[str] | None = None) -> dict[str, Any]:
+        return self.create_project_token(project_id, name, scopes or ["admin_agents"], purpose="automation")
+
+    def list_tokens(self, subject_type: str | None = None) -> list[dict[str, Any]]:
+        path = "/tokens"
+        if subject_type:
+            path = f"/tokens?subject_type={subject_type}"
+        return self._request("GET", path)
+
+    def revoke_token_by_jti(self, jti: str) -> dict[str, Any]:
+        return self._request("POST", "/tokens/revoke", json={"jti": jti})
+
+    def delete_agent(self, agent_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/agents/{agent_id}")
+
+    def get_agent(self, agent_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/agents/{agent_id}")
+
+    def issue_token(self, agent_id: str) -> dict[str, Any]:
+        return self._request("POST", "/auth/token", json={"agent_id": agent_id})
+
+    def sync_tools(self, permissions: list[dict[str, str]]) -> dict[str, Any]:
+        return self._request("POST", "/policy/permissions/sync", json={"permissions": permissions})
+
+    def list_permissions(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/policy/permissions")
+
+    def explain_token(self, token: str | None = None) -> dict[str, Any]:
+        payload = self.decode_token(token)
+        if not payload:
+            raise InvalidTokenError("Unable to decode token")
+        scopes = list(payload.get("scopes") or [])
+        project_id = payload.get("project_id")
+        agent_id = payload.get("agent_id")
+        purpose = payload.get("purpose")
+        if not project_id:
+            project_id = next((scope.split(":", 1)[1] for scope in scopes if isinstance(scope, str) and scope.startswith("project:")), None)
+        if not agent_id:
+            agent_id = next((scope.split(":", 1)[1] for scope in scopes if isinstance(scope, str) and scope.startswith("agent:")), None)
+        if not purpose:
+            purpose = next((scope.split(":", 1)[1] for scope in scopes if isinstance(scope, str) and scope.startswith("purpose:")), None)
+        return {
+            "principal_id": payload.get("sub") or payload.get("principal_id"),
+            "principal_type": payload.get("principal_type") or payload.get("subject_type") or payload.get("sub_type"),
+            "role": payload.get("role"),
+            "email": payload.get("email"),
+            "purpose": purpose,
+            "project_id": project_id,
+            "agent_id": agent_id,
+            "scopes": scopes,
+            "auth_source": self.auth_source,
+        }
+
+    def execution_context(self, *, agent_id: str | None = None, role: str | None = None, context: dict[str, Any] | None = None, require_runtime_binding: bool = False) -> ExecutionContext:
+        if not self.token:
+            raise InvalidTokenError("No token available to derive execution context")
+        payload = self.decode_token(self.token)
+        if not payload:
+            raise InvalidTokenError("Unable to decode token for execution context")
+        ctx = execution_context_from_token_payload(payload, agent_id=agent_id, role=role, context=context)
+        if require_runtime_binding:
+            token_info = self.explain_token()
+            if token_info.get("purpose") != "runtime":
+                raise InvalidTokenError("Token is not bound for runtime usage")
+            if not ctx.project_id:
+                raise InvalidTokenError("Runtime token is missing project binding")
+            if not ctx.agent_id:
+                raise InvalidTokenError("Runtime token is missing agent binding")
+        return ctx
+
+    def runtime_context(self, *, context: dict[str, Any] | None = None, role: str | None = None) -> ExecutionContext:
+        return self.execution_context(context=context, role=role, require_runtime_binding=True)
+
+    def evaluate(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) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            "/policy/evaluate",
+            json={
+                "principal_id": principal_id,
+                "action": action,
+                "resource": resource,
+                "granted_scopes": granted_scopes or [],
+                "role": role,
+                "context": context or {},
+            },
+        )
+
+    def auth_context(self, principal_id: str, scopes: list[str], role: str | None = None, principal_type: str = "agent", email: str | None = None) -> AuthContext:
+        return AuthContext(
+            principal_id=principal_id,
+            principal_type=principal_type,
+            scopes=scopes,
+            role=role,
+            email=email,
+        )