agentlock 1.0.0__py3-none-any.whl

agentlock/cli.py

@@ -0,0 +1,308 @@
+"""AgentLock CLI — validate schemas, inspect audit logs, manage tools.
+
+Usage::
+
+    agentlock validate tool.json          # Validate a tool definition
+    agentlock audit --tool send_email     # Query audit logs
+    agentlock schema                      # Print the JSON schema
+    agentlock init                        # Generate a starter agentlock.json
+    agentlock inspect tool.json           # Display permissions summary
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from agentlock import __version__
+
+
+def _validate(args: argparse.Namespace) -> int:
+    """Validate a tool definition file against the AgentLock schema."""
+    from pydantic import ValidationError
+
+    from agentlock.schema import AgentLockPermissions, ToolDefinition
+
+    path = Path(args.file)
+    if not path.exists():
+        print(f"Error: file not found: {path}", file=sys.stderr)
+        return 1
+
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as e:
+        print(f"Error: invalid JSON: {e}", file=sys.stderr)
+        return 1
+
+    errors: list[str] = []
+
+    # If the file is a full tool definition
+    if "name" in data:
+        try:
+            tool = ToolDefinition(**data)
+            perms = tool.agentlock
+        except ValidationError as e:
+            errors.extend(str(err) for err in e.errors())
+    elif "agentlock" in data:
+        try:
+            perms = AgentLockPermissions(**data["agentlock"])
+        except ValidationError as e:
+            errors.extend(str(err) for err in e.errors())
+    else:
+        try:
+            perms = AgentLockPermissions(**data)
+        except ValidationError as e:
+            errors.extend(str(err) for err in e.errors())
+
+    if errors:
+        print(f"INVALID — {len(errors)} error(s):")
+        for err in errors:
+            print(f"  {err}")
+        return 1
+
+    print(f"VALID — {path.name}")
+    print(f"  Version:     {perms.version}")
+    print(f"  Risk level:  {perms.risk_level.value}")
+    print(f"  Auth:        {'required' if perms.requires_auth else 'not required'}")
+    print(f"  Roles:       {', '.join(perms.allowed_roles) or '(none — deny all)'}")
+    if perms.rate_limit:
+        print(f"  Rate limit:  {perms.rate_limit.max_calls}/{perms.rate_limit.window_seconds}s")
+    if perms.data_policy.prohibited_in_output:
+        print(f"  Redacts:     {', '.join(perms.data_policy.prohibited_in_output)}")
+    if perms.human_approval.required:
+        thr = perms.human_approval.threshold.value
+        ch = perms.human_approval.channel.value
+        print(f"  Approval:    {thr} via {ch}")
+    return 0
+
+
+def _schema(args: argparse.Namespace) -> int:
+    """Print the AgentLock JSON schema."""
+    from agentlock.schema import AgentLockPermissions
+
+    schema = AgentLockPermissions.model_json_schema()
+    print(json.dumps(schema, indent=2))
+    return 0
+
+
+def _init(args: argparse.Namespace) -> int:
+    """Generate a starter tool definition with AgentLock permissions."""
+    template = {
+        "name": "my_tool",
+        "description": "Description of what this tool does",
+        "parameters": {
+            "param1": "string",
+            "param2": "integer",
+        },
+        "agentlock": {
+            "version": "1.0",
+            "risk_level": "medium",
+            "requires_auth": True,
+            "auth_methods": ["oauth2"],
+            "allowed_roles": ["user", "admin"],
+            "scope": {
+                "data_boundary": "authenticated_user_only",
+                "max_records": 10,
+            },
+            "rate_limit": {
+                "max_calls": 100,
+                "window_seconds": 3600,
+            },
+            "data_policy": {
+                "input_classification": "public",
+                "output_classification": "internal",
+                "prohibited_in_output": [],
+                "redaction": "none",
+            },
+            "audit": {
+                "log_level": "standard",
+                "include_parameters": True,
+                "retention_days": 90,
+            },
+            "human_approval": {
+                "required": False,
+            },
+        },
+    }
+    output = Path(args.output) if args.output else Path("agentlock-tool.json")
+    output.write_text(json.dumps(template, indent=2) + "\n")
+    print(f"Created {output}")
+    print("Edit the file and run: agentlock validate " + str(output))
+    return 0
+
+
+def _inspect(args: argparse.Namespace) -> int:
+    """Display a human-readable summary of a tool's permissions."""
+    path = Path(args.file)
+    if not path.exists():
+        print(f"Error: file not found: {path}", file=sys.stderr)
+        return 1
+
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as e:
+        print(f"Error: invalid JSON: {e}", file=sys.stderr)
+        return 1
+
+    from pydantic import ValidationError
+
+    from agentlock.schema import AgentLockPermissions
+
+    tool_name = data.get("name", path.stem)
+
+    if "agentlock" in data:
+        perms_data = data["agentlock"]
+    elif "name" in data:
+        perms_data = data.get("agentlock", {})
+    else:
+        perms_data = data
+
+    try:
+        perms = AgentLockPermissions(**perms_data)
+    except ValidationError as e:
+        print(f"Error: invalid permissions: {e}", file=sys.stderr)
+        return 1
+
+    risk_colors = {
+        "none": "\033[92m",     # green
+        "low": "\033[92m",      # green
+        "medium": "\033[93m",   # yellow
+        "high": "\033[91m",     # red
+        "critical": "\033[91m\033[1m",  # bold red
+    }
+    reset = "\033[0m"
+    rc = risk_colors.get(perms.risk_level.value, "")
+
+    print(f"\n  Tool: {tool_name}")
+    print(f"  {'─' * 50}")
+    print(f"  Risk:          {rc}{perms.risk_level.value.upper()}{reset}")
+    print(f"  Auth required: {'Yes' if perms.requires_auth else 'No'}")
+    print(f"  Auth methods:  {', '.join(m.value for m in perms.auth_methods)}")
+    print(f"  Allowed roles: {', '.join(perms.allowed_roles) or '(none — DENY ALL)'}")
+    print(f"  Data boundary: {perms.scope.data_boundary.value}")
+    if perms.scope.max_records:
+        print(f"  Max records:   {perms.scope.max_records}")
+    if perms.rate_limit:
+        rl = perms.rate_limit
+        print(f"  Rate limit:    {rl.max_calls} calls / {rl.window_seconds}s")
+    print(f"  Input class:   {perms.data_policy.input_classification.value}")
+    print(f"  Output class:  {perms.data_policy.output_classification.value}")
+    if perms.data_policy.prohibited_in_output:
+        types = ", ".join(perms.data_policy.prohibited_in_output)
+        mode = perms.data_policy.redaction.value
+        print(f"  Redacts:       {types} ({mode})")
+    print(f"  Session TTL:   {perms.session.max_duration_seconds}s")
+    print(f"  Audit level:   {perms.audit.log_level.value}")
+    print(f"  Retention:     {perms.audit.retention_days} days")
+    if perms.human_approval.required:
+        thr = perms.human_approval.threshold.value
+        ch = perms.human_approval.channel.value
+        print(f"  Approval:      {thr} via {ch}")
+    else:
+        print("  Approval:      not required")
+    print()
+    return 0
+
+
+def _audit_query(args: argparse.Namespace) -> int:
+    """Query the audit log."""
+    import time
+
+    from agentlock.audit import FileAuditBackend
+
+    path = args.log or str(Path.home() / ".agentlock" / "audit.jsonl")
+    backend = FileAuditBackend(path)
+
+    since = None
+    if args.since:
+        # Parse relative time like "1h", "24h", "7d"
+        val = args.since
+        if val.endswith("h"):
+            since = time.time() - int(val[:-1]) * 3600
+        elif val.endswith("d"):
+            since = time.time() - int(val[:-1]) * 86400
+        elif val.endswith("m"):
+            since = time.time() - int(val[:-1]) * 60
+
+    records = backend.query(
+        tool_name=args.tool,
+        user_id=args.user,
+        since=since,
+        limit=args.limit,
+    )
+
+    if not records:
+        print("No audit records found.")
+        return 0
+
+    for r in records:
+        ts = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime(r.timestamp))
+        action_color = "\033[92m" if r.action == "allowed" else "\033[91m"
+        reset = "\033[0m"
+        print(
+            f"  {ts}  {r.audit_id}  {r.tool_name:20s}  "
+            f"{action_color}{r.action:8s}{reset}  "
+            f"{r.user_id or '-':15s}  {r.role or '-':10s}  "
+            f"{r.reason or ''}"
+        )
+
+    print(f"\n  {len(records)} record(s)")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="agentlock",
+        description="AgentLock — Authorization framework for AI agent tool calls",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"agentlock {__version__}"
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    # validate
+    p_validate = sub.add_parser("validate", help="Validate a tool definition")
+    p_validate.add_argument("file", help="Path to JSON file")
+
+    # schema
+    sub.add_parser("schema", help="Print the AgentLock JSON schema")
+
+    # init
+    p_init = sub.add_parser("init", help="Generate a starter tool definition")
+    p_init.add_argument("-o", "--output", help="Output path", default=None)
+
+    # inspect
+    p_inspect = sub.add_parser("inspect", help="Display permissions summary")
+    p_inspect.add_argument("file", help="Path to JSON file")
+
+    # audit
+    p_audit = sub.add_parser("audit", help="Query audit logs")
+    p_audit.add_argument("--tool", help="Filter by tool name")
+    p_audit.add_argument("--user", help="Filter by user ID")
+    p_audit.add_argument("--since", help="Time window (e.g. 1h, 24h, 7d)")
+    p_audit.add_argument("--limit", type=int, default=50, help="Max records")
+    p_audit.add_argument("--log", help="Audit log file path")
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    handlers = {
+        "validate": _validate,
+        "schema": _schema,
+        "init": _init,
+        "inspect": _inspect,
+        "audit": _audit_query,
+    }
+
+    return handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentlock/decorators.py

@@ -0,0 +1,182 @@
+"""Decorators for one-line tool protection.
+
+Example::
+
+    from agentlock import agentlock, AuthorizationGate
+
+    gate = AuthorizationGate()
+
+    @agentlock(
+        gate,
+        risk_level="high",
+        requires_auth=True,
+        allowed_roles=["admin"],
+        rate_limit={"max_calls": 5, "window_seconds": 3600},
+    )
+    def send_email(to: str, subject: str, body: str) -> str:
+        # ... send the email ...
+        return "sent"
+
+    # Calling the decorated function requires authorization context
+    result = send_email(to="bob@co.com", subject="Hi", body="Hello",
+                        _user_id="alice", _role="admin")
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from agentlock.gate import AuthorizationGate
+from agentlock.schema import AgentLockPermissions
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_RESERVED_KWARGS = {"_user_id", "_role", "_session_id", "_metadata"}
+
+
+def agentlock(
+    gate: AuthorizationGate,
+    *,
+    name: str | None = None,
+    risk_level: str = "high",
+    requires_auth: bool = True,
+    allowed_roles: list[str] | None = None,
+    rate_limit: dict[str, int] | None = None,
+    data_policy: dict[str, Any] | None = None,
+    human_approval: dict[str, Any] | None = None,
+    scope: dict[str, Any] | None = None,
+    audit: dict[str, Any] | None = None,
+    session: dict[str, Any] | None = None,
+    permissions: AgentLockPermissions | dict[str, Any] | None = None,
+) -> Callable[[F], F]:
+    """Decorator that wraps a function with AgentLock authorization.
+
+    All AgentLock permission fields can be passed as keyword arguments.
+    Alternatively, pass a pre-built ``permissions`` object.
+
+    The decorated function accepts special ``_user_id``, ``_role``,
+    ``_session_id``, and ``_metadata`` keyword arguments for auth context.
+    These are stripped before calling the underlying function.
+
+    Args:
+        gate: The AuthorizationGate instance.
+        name: Tool name override.  Defaults to function name.
+        risk_level: Risk classification.
+        requires_auth: Whether authentication is required.
+        allowed_roles: Roles permitted to invoke.
+        rate_limit: Rate limiting config dict.
+        data_policy: Data policy config dict.
+        human_approval: Human approval config dict.
+        scope: Scope config dict.
+        audit: Audit config dict.
+        session: Session config dict.
+        permissions: Pre-built permissions object (overrides other fields).
+
+    Returns:
+        Decorator that protects the function.
+    """
+
+    def decorator(func: F) -> F:
+        tool_name = name or func.__name__
+
+        # Build permissions
+        if permissions is not None:
+            if isinstance(permissions, dict):
+                perms = AgentLockPermissions(**permissions)
+            else:
+                perms = permissions
+        else:
+            perms_dict: dict[str, Any] = {
+                "risk_level": risk_level,
+                "requires_auth": requires_auth,
+            }
+            if allowed_roles is not None:
+                perms_dict["allowed_roles"] = allowed_roles
+            if rate_limit is not None:
+                perms_dict["rate_limit"] = rate_limit
+            if data_policy is not None:
+                perms_dict["data_policy"] = data_policy
+            if human_approval is not None:
+                perms_dict["human_approval"] = human_approval
+            if scope is not None:
+                perms_dict["scope"] = scope
+            if audit is not None:
+                perms_dict["audit"] = audit
+            if session is not None:
+                perms_dict["session"] = session
+            perms = AgentLockPermissions(**perms_dict)
+
+        # Register with gate
+        gate.register_tool(tool_name, perms)
+
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                user_id = kwargs.pop("_user_id", "")
+                role = kwargs.pop("_role", "")
+                kwargs.pop("_session_id", "")
+                meta = kwargs.pop("_metadata", None)
+
+                # Authorize through the gate
+                auth_result = gate.authorize(
+                    tool_name,
+                    user_id=user_id,
+                    role=role,
+                    parameters=kwargs,
+                    metadata=meta,
+                )
+                auth_result.raise_if_denied()
+                assert auth_result.token is not None
+
+                # Execute: await the async function directly, then run
+                # through the gate's redaction/audit via execute()
+                # We wrap in a sync callable for gate.execute() compatibility
+                captured_result = await func(*args, **kwargs)
+
+                # Apply redaction if configured
+                redacted = gate.redact_output(tool_name, captured_result) \
+                    if isinstance(captured_result, str) else None
+                if redacted and redacted.was_redacted:
+                    # Consume token and return redacted output
+                    gate.token_store.validate_and_consume(
+                        auth_result.token.token_id, tool_name, kwargs,
+                    )
+                    return redacted.redacted
+
+                # Consume token for audit trail
+                gate.token_store.validate_and_consume(
+                    auth_result.token.token_id, tool_name, kwargs,
+                )
+                return captured_result
+
+            async_wrapper._agentlock_tool_name = tool_name  # type: ignore[attr-defined]
+            async_wrapper._agentlock_permissions = perms  # type: ignore[attr-defined]
+            return async_wrapper  # type: ignore[return-value]
+
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                user_id = kwargs.pop("_user_id", "")
+                role = kwargs.pop("_role", "")
+                kwargs.pop("_session_id", "")
+                meta = kwargs.pop("_metadata", None)
+
+                return gate.call(
+                    tool_name,
+                    lambda **p: func(*args, **p),
+                    user_id=user_id,
+                    role=role,
+                    parameters=kwargs,
+                    metadata=meta,
+                )
+
+            sync_wrapper._agentlock_tool_name = tool_name  # type: ignore[attr-defined]
+            sync_wrapper._agentlock_permissions = perms  # type: ignore[attr-defined]
+            return sync_wrapper  # type: ignore[return-value]
+
+    return decorator

agentlock/exceptions.py

@@ -0,0 +1,142 @@
+"""AgentLock exception hierarchy."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from agentlock.types import AuditId, DenialReason, RoleName
+
+
+class AgentLockError(Exception):
+    """Base exception for all AgentLock errors."""
+
+
+class DeniedError(AgentLockError):
+    """Tool call was denied by the authorization gate.
+
+    Attributes:
+        reason: Standardized denial code.
+        detail: Human-readable explanation.
+        required_role: Role needed for access, if applicable.
+        current_role: Caller's current role, if known.
+        suggestion: Actionable guidance for the caller.
+        audit_id: Audit record identifier for this denial.
+    """
+
+    def __init__(
+        self,
+        reason: DenialReason | str,
+        detail: str = "",
+        *,
+        required_role: RoleName | None = None,
+        current_role: RoleName | None = None,
+        suggestion: str = "",
+        audit_id: AuditId | None = None,
+    ) -> None:
+        self.reason = str(reason.value if hasattr(reason, "value") else reason)
+        self.detail = detail
+        self.required_role = required_role
+        self.current_role = current_role
+        self.suggestion = suggestion
+        self.audit_id = audit_id
+        super().__init__(self._format())
+
+    def _format(self) -> str:
+        parts = [f"denied: {self.reason}"]
+        if self.detail:
+            parts.append(self.detail)
+        return " — ".join(parts)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to the AgentLock denial response format."""
+        d: dict[str, Any] = {
+            "status": "denied",
+            "reason": self.reason,
+        }
+        if self.required_role:
+            d["required_role"] = self.required_role
+        if self.current_role:
+            d["current_role"] = self.current_role
+        if self.suggestion:
+            d["suggestion"] = self.suggestion
+        if self.audit_id:
+            d["audit_id"] = self.audit_id
+        return d
+
+
+class AuthenticationRequiredError(DeniedError):
+    """Caller must authenticate before this tool can execute."""
+
+    def __init__(self, auth_methods: list[str] | None = None, **kwargs: Any) -> None:
+        self.auth_methods = auth_methods or []
+        super().__init__(reason="not_authenticated", **kwargs)
+
+
+class InsufficientRoleError(DeniedError):
+    """Caller's role does not include required permissions."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(reason="insufficient_role", **kwargs)
+
+
+class ScopeViolationError(DeniedError):
+    """Request exceeds the caller's data boundary or record limits."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(reason="scope_violation", **kwargs)
+
+
+class RateLimitedError(DeniedError):
+    """Caller has exceeded rate limits for this tool."""
+
+    def __init__(
+        self,
+        retry_after_seconds: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.retry_after_seconds = retry_after_seconds
+        super().__init__(reason="rate_limited", **kwargs)
+
+
+class SessionExpiredError(DeniedError):
+    """Session has expired; re-authentication required."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(reason="session_expired", **kwargs)
+
+
+class ApprovalRequiredError(DeniedError):
+    """Human approval is required before execution."""
+
+    def __init__(
+        self,
+        channel: str = "push_notification",
+        **kwargs: Any,
+    ) -> None:
+        self.channel = channel
+        super().__init__(reason="approval_required", **kwargs)
+
+
+class TokenError(AgentLockError):
+    """Base for token-related errors."""
+
+
+class TokenInvalidError(TokenError):
+    """Token is malformed or unrecognized."""
+
+
+class TokenExpiredError(TokenError):
+    """Token has passed its expiry time."""
+
+
+class TokenReplayedError(TokenError):
+    """Token has already been consumed (single-use enforcement)."""
+
+
+class SchemaValidationError(AgentLockError):
+    """AgentLock permissions block failed validation."""
+
+
+class ConfigurationError(AgentLockError):
+    """Library misconfiguration."""