agentonboard-sdk 0.1.0__py3-none-any.whl

agentonboard/__init__.py

@@ -0,0 +1,60 @@
+"""
+AgentOnboard Python SDK — Universal identity layer for AI agents.
+"""
+
+from agentonboard.account import (
+    AccountCreator,
+    AccountOutcome,
+    AccountResolver,
+    AgentIdentity,
+    AsyncAccountCreator,
+    AsyncAccountResolver,
+    create_agent_account,
+    create_agent_account_async,
+    normalize_email,
+    verify_agent_account,
+    verify_agent_account_async,
+)
+from agentonboard.codes import (
+    ACCOUNT_ERROR_DESCRIPTIONS,
+    VERIFY_ERROR_DESCRIPTIONS,
+    AccountErrorCode,
+    VerifyErrorCode,
+    status_from_code,
+)
+from agentonboard.verify import (
+    DEFAULT_CLOCK_TOLERANCE_SECONDS,
+    Verifier,
+    VerifyAgentTokenResult,
+    normalize_audience,
+    verify_agent_token,
+    verify_agent_token_async,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ACCOUNT_ERROR_DESCRIPTIONS",
+    "AccountCreator",
+    "AccountErrorCode",
+    "AccountOutcome",
+    "AccountResolver",
+    "AgentIdentity",
+    "AsyncAccountCreator",
+    "AsyncAccountResolver",
+    "DEFAULT_CLOCK_TOLERANCE_SECONDS",
+    "VERIFY_ERROR_DESCRIPTIONS",
+    "Verifier",
+    "VerifyAgentTokenResult",
+    "VerifyErrorCode",
+    "__version__",
+    "create_agent_account",
+    "create_agent_account_async",
+    "normalize_audience",
+    "normalize_email",
+    "status_from_code",
+    "verify_agent_account",
+    "verify_agent_account_async",
+    "verify_agent_token",
+    "verify_agent_token_async",
+]

agentonboard/account.py

@@ -0,0 +1,320 @@
+"""
+Account mapping and automated provisioning boundaries for AgentOnboard.
+
+Implements verify_agent_account and create_agent_account per ADR 0002 and
+docs/decisions/0007-agents-can-create-partner-accounts.md.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from agentonboard.codes import AccountErrorCode
+from agentonboard.verify import (
+    DEFAULT_CLOCK_TOLERANCE_SECONDS,
+    verify_agent_token,
+    verify_agent_token_async,
+)
+
+TUser = TypeVar("TUser")
+
+
+@dataclass(slots=True, frozen=True)
+class AgentIdentity:
+    """The verified identity, and the only thing that crosses into your resolver/creator."""
+
+    email: str
+
+
+def normalize_email(email: str) -> str:
+    """Normalizes an email address for database lookups by trimming whitespace and converting to lowercase."""
+    if not email or not isinstance(email, str):
+        return ""
+    return email.strip().lower()
+
+
+@dataclass(slots=True, frozen=True)
+class AccountOutcome(Generic[TUser]):
+    ok: bool
+    email: str | None = None
+    user: TUser | None = None
+    created: bool = False
+    code: AccountErrorCode | None = None
+    error: str | None = None
+
+
+AccountResolver = Callable[[AgentIdentity], TUser | None]
+AccountCreator = Callable[[AgentIdentity], TUser]
+AsyncAccountResolver = Callable[[AgentIdentity], Awaitable[TUser | None] | TUser | None]
+AsyncAccountCreator = Callable[[AgentIdentity], Awaitable[TUser] | TUser]
+
+
+def verify_agent_account(
+    token: str,
+    *,
+    audience: str,
+    resolver: AccountResolver[TUser],
+    issuer: str | None = None,
+    jwks_url: str | None = None,
+    jwks: dict[str, Any] | None = None,
+    fetch_jwks: Callable[[str], dict[str, Any]] | None = None,
+    clock_tolerance_seconds: int = DEFAULT_CLOCK_TOLERANCE_SECONDS,
+) -> AccountOutcome[TUser]:
+    """
+    Verifies an agent session token, then maps the verified email to your own user.
+    Never creates an account. If no account exists, returns ACCOUNT_REQUIRED.
+    """
+    verify_result = verify_agent_token(
+        token=token,
+        audience=audience,
+        issuer=issuer,
+        jwks_url=jwks_url,
+        jwks=jwks,
+        fetch_jwks=fetch_jwks,
+        clock_tolerance_seconds=clock_tolerance_seconds,
+    )
+
+    if not verify_result.ok:
+        return AccountOutcome(
+            ok=False,
+            code=verify_result.code,
+            error=verify_result.error,
+        )
+
+    verified_email = verify_result.email or ""
+    identity = AgentIdentity(email=verified_email)
+
+    try:
+        user = resolver(identity)
+    except Exception:
+        return AccountOutcome(
+            ok=False,
+            code="RESOLVER_ERROR",
+            error="The account resolver threw. This is a fault in the resolver, not the token.",
+        )
+
+    if user is None:
+        return AccountOutcome(
+            ok=False,
+            code="ACCOUNT_REQUIRED",
+            error="This identity has no account at your service; send the human to connect their account, then retry.",
+        )
+
+    return AccountOutcome(
+        ok=True,
+        email=verified_email,
+        user=user,
+        created=False,
+    )
+
+
+async def verify_agent_account_async(
+    token: str,
+    *,
+    audience: str,
+    resolver: AsyncAccountResolver[TUser],
+    issuer: str | None = None,
+    jwks_url: str | None = None,
+    jwks: dict[str, Any] | None = None,
+    fetch_jwks: Callable[[str], dict[str, Any]] | None = None,
+    fetch_jwks_async: Callable[[str], Awaitable[dict[str, Any]]] | None = None,
+    clock_tolerance_seconds: int = DEFAULT_CLOCK_TOLERANCE_SECONDS,
+) -> AccountOutcome[TUser]:
+    """Asynchronous variant of verify_agent_account."""
+    verify_result = await verify_agent_token_async(
+        token=token,
+        audience=audience,
+        issuer=issuer,
+        jwks_url=jwks_url,
+        jwks=jwks,
+        fetch_jwks=fetch_jwks,
+        fetch_jwks_async=fetch_jwks_async,
+        clock_tolerance_seconds=clock_tolerance_seconds,
+    )
+
+    if not verify_result.ok:
+        return AccountOutcome(
+            ok=False,
+            code=verify_result.code,
+            error=verify_result.error,
+        )
+
+    verified_email = verify_result.email or ""
+    identity = AgentIdentity(email=verified_email)
+
+    try:
+        user_val = resolver(identity)
+        if inspect.isawaitable(user_val):
+            user = await user_val
+        else:
+            user = user_val
+    except Exception:
+        return AccountOutcome(
+            ok=False,
+            code="RESOLVER_ERROR",
+            error="The account resolver threw. This is a fault in the resolver, not the token.",
+        )
+
+    if user is None:
+        return AccountOutcome(
+            ok=False,
+            code="ACCOUNT_REQUIRED",
+            error="This identity has no account at your service; send the human to connect their account, then retry.",
+        )
+
+    return AccountOutcome(
+        ok=True,
+        email=verified_email,
+        user=user,
+        created=False,
+    )
+
+
+def create_agent_account(
+    token: str,
+    *,
+    audience: str,
+    resolver: AccountResolver[TUser],
+    creator: AccountCreator[TUser],
+    issuer: str | None = None,
+    jwks_url: str | None = None,
+    jwks: dict[str, Any] | None = None,
+    fetch_jwks: Callable[[str], dict[str, Any]] | None = None,
+    clock_tolerance_seconds: int = DEFAULT_CLOCK_TOLERANCE_SECONDS,
+) -> AccountOutcome[TUser]:
+    """
+    Verifies an agent session token, maps the email to a user, and if no user exists,
+    calls creator once to provision the account.
+    """
+    verify_result = verify_agent_token(
+        token=token,
+        audience=audience,
+        issuer=issuer,
+        jwks_url=jwks_url,
+        jwks=jwks,
+        fetch_jwks=fetch_jwks,
+        clock_tolerance_seconds=clock_tolerance_seconds,
+    )
+
+    if not verify_result.ok:
+        return AccountOutcome(
+            ok=False,
+            code=verify_result.code,
+            error=verify_result.error,
+        )
+
+    verified_email = verify_result.email or ""
+    identity = AgentIdentity(email=verified_email)
+
+    try:
+        user = resolver(identity)
+    except Exception:
+        return AccountOutcome(
+            ok=False,
+            code="RESOLVER_ERROR",
+            error="The account resolver threw. This is a fault in the resolver, not the token.",
+        )
+
+    if user is not None:
+        return AccountOutcome(
+            ok=True,
+            email=verified_email,
+            user=user,
+            created=False,
+        )
+
+    try:
+        new_user = creator(identity)
+    except Exception:
+        return AccountOutcome(
+            ok=False,
+            code="RESOLVER_ERROR",
+            error="The account creator threw. This is a fault in the creator, not the token.",
+        )
+
+    return AccountOutcome(
+        ok=True,
+        email=verified_email,
+        user=new_user,
+        created=True,
+    )
+
+
+async def create_agent_account_async(
+    token: str,
+    *,
+    audience: str,
+    resolver: AsyncAccountResolver[TUser],
+    creator: AsyncAccountCreator[TUser],
+    issuer: str | None = None,
+    jwks_url: str | None = None,
+    jwks: dict[str, Any] | None = None,
+    fetch_jwks: Callable[[str], dict[str, Any]] | None = None,
+    fetch_jwks_async: Callable[[str], Awaitable[dict[str, Any]]] | None = None,
+    clock_tolerance_seconds: int = DEFAULT_CLOCK_TOLERANCE_SECONDS,
+) -> AccountOutcome[TUser]:
+    """Asynchronous variant of create_agent_account."""
+    verify_result = await verify_agent_token_async(
+        token=token,
+        audience=audience,
+        issuer=issuer,
+        jwks_url=jwks_url,
+        jwks=jwks,
+        fetch_jwks=fetch_jwks,
+        fetch_jwks_async=fetch_jwks_async,
+        clock_tolerance_seconds=clock_tolerance_seconds,
+    )
+
+    if not verify_result.ok:
+        return AccountOutcome(
+            ok=False,
+            code=verify_result.code,
+            error=verify_result.error,
+        )
+
+    verified_email = verify_result.email or ""
+    identity = AgentIdentity(email=verified_email)
+
+    try:
+        user_val = resolver(identity)
+        if inspect.isawaitable(user_val):
+            user = await user_val
+        else:
+            user = user_val
+    except Exception:
+        return AccountOutcome(
+            ok=False,
+            code="RESOLVER_ERROR",
+            error="The account resolver threw. This is a fault in the resolver, not the token.",
+        )
+
+    if user is not None:
+        return AccountOutcome(
+            ok=True,
+            email=verified_email,
+            user=user,
+            created=False,
+        )
+
+    try:
+        new_user_val = creator(identity)
+        if inspect.isawaitable(new_user_val):
+            new_user = await new_user_val
+        else:
+            new_user = new_user_val
+    except Exception:
+        return AccountOutcome(
+            ok=False,
+            code="RESOLVER_ERROR",
+            error="The account creator threw. This is a fault in the creator, not the token.",
+        )
+
+    return AccountOutcome(
+        ok=True,
+        email=verified_email,
+        user=new_user,
+        created=True,
+    )

agentonboard/codes.py

@@ -0,0 +1,76 @@
+"""
+Every failure verify_agent_token and verify_agent_account can report.
+
+Published vocabulary: codes are only ever added, never renamed or removed, because partners
+branch on them. Keep this list short — every code is a decision each language SDK has
+to make identically (plans/0008-sdk-design.md §6).
+"""
+
+from typing import Literal
+
+VerifyErrorCode = Literal[
+    "EXPIRED",
+    "INVALID_SIGNATURE",
+    "AUDIENCE_MISMATCH",
+    "ISSUER_MISMATCH",
+    "MALFORMED_TOKEN",
+    "CONFIG_ERROR",
+    "UNKNOWN_KEY",
+    "KEY_SOURCE_UNAVAILABLE",
+    "MISSING_EMAIL",
+]
+
+AccountErrorCode = Literal[
+    VerifyErrorCode,
+    "ACCOUNT_REQUIRED",
+    "RESOLVER_ERROR",
+]
+
+VERIFY_ERROR_DESCRIPTIONS: dict[VerifyErrorCode, str] = {
+    "EXPIRED": "The token's exp claim is in the past, beyond the clock-skew tolerance.",
+    "INVALID_SIGNATURE": (
+        "The signature did not verify against a published key, or the token used an "
+        "algorithm this SDK does not accept."
+    ),
+    "AUDIENCE_MISMATCH": "The token was minted for a different audience, or carries no aud claim.",
+    "ISSUER_MISMATCH": "The token was minted by a different issuer, or carries no iss claim.",
+    "MALFORMED_TOKEN": (
+        "The token is not a readable JWT, or a claim this SDK requires is absent or unusable."
+    ),
+    "CONFIG_ERROR": "The call itself is wrong: audience, issuer, JWKS URL, or clock-skew tolerance.",
+    "UNKNOWN_KEY": (
+        "The token's kid matched no key in the key set this SDK could obtain. The code does "
+        "not say why: the key may be revoked or rotated away, the token may be forged, or "
+        "the key endpoint may be unreachable and leave this SDK holding an out-of-date set."
+    ),
+    "KEY_SOURCE_UNAVAILABLE": (
+        "This SDK could not obtain a signing key: the key set could not be fetched, the "
+        "published set is not one this SDK can verify against, or it publishes more than one "
+        "key for the token's kid."
+    ),
+    "MISSING_EMAIL": "The token verified but carries no usable email claim to identify the human.",
+}
+
+ACCOUNT_ERROR_DESCRIPTIONS: dict[AccountErrorCode, str] = {
+    **VERIFY_ERROR_DESCRIPTIONS,  # type: ignore[dict-item]
+    "ACCOUNT_REQUIRED": (
+        "The token verified, but the partner resolver returned no account for this identity."
+    ),
+    "RESOLVER_ERROR": "The partner's account lookup or creation callback threw an error.",
+}
+
+
+def status_from_code(code: str | None) -> int:
+    """
+    Turns a verification or account failure code into an HTTP status code.
+    Rules per agent-token-v1 statusMapping:
+    - 403 for ACCOUNT_REQUIRED
+    - 500 for RESOLVER_ERROR and CONFIG_ERROR
+    - 401 for all other error codes
+    """
+    if code == "ACCOUNT_REQUIRED":
+        return 403
+    if code in ("RESOLVER_ERROR", "CONFIG_ERROR"):
+        return 500
+    return 401
+

agentonboard/frameworks/__init__.py

@@ -0,0 +1,3 @@
+"""
+Framework integrations for AgentOnboard.
+"""

agentonboard/frameworks/fastapi.py

@@ -0,0 +1,119 @@
+"""
+FastAPI security dependency for AgentOnboard.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from fastapi import HTTPException, Request, status
+from fastapi.openapi.models import HTTPBearer as HTTPBearerModel
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from fastapi.security.base import SecurityBase
+
+from agentonboard.account import (
+    AgentIdentity,
+    AsyncAccountCreator,
+    AsyncAccountResolver,
+    create_agent_account_async,
+    verify_agent_account_async,
+)
+from agentonboard.codes import status_from_code
+from agentonboard.verify import verify_agent_token_async
+
+TUser = TypeVar("TUser")
+
+
+class AgentBearerAuth(SecurityBase, Generic[TUser]):
+    """
+    FastAPI dependency for verifying AgentOnboard session tokens and resolving accounts.
+
+    Usage:
+        auth = AgentBearerAuth(audience="notes.com")
+
+        @app.get("/items")
+        async def read_items(identity: AgentIdentity = Depends(auth)):
+            return {"user": identity.email}
+    """
+
+    def __init__(
+        self,
+        *,
+        audience: str,
+        resolver: AsyncAccountResolver[TUser] | None = None,
+        creator: AsyncAccountCreator[TUser] | None = None,
+        auto_create: bool = False,
+        issuer: str | None = None,
+        jwks_url: str | None = None,
+        jwks: dict[str, Any] | None = None,
+        auto_error: bool = True,
+    ) -> None:
+        self.model = HTTPBearerModel()
+        self.scheme_name = self.__class__.__name__
+        self.bearer = HTTPBearer(auto_error=auto_error)
+        self.audience = audience
+        self.resolver = resolver
+        self.creator = creator
+        self.auto_create = auto_create
+        self.issuer = issuer
+        self.jwks_url = jwks_url
+        self.jwks = jwks
+
+    async def __call__(
+        self, request: Request
+    ) -> AgentIdentity | TUser:
+        credentials: HTTPAuthorizationCredentials | None = await self.bearer(request)
+        if not credentials or not credentials.credentials:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail={"code": "MALFORMED_TOKEN", "error": "Missing authorization bearer token"},
+            )
+
+        token = credentials.credentials
+
+        if self.resolver is None:
+            # Token verification only
+            result = await verify_agent_token_async(
+                token=token,
+                audience=self.audience,
+                issuer=self.issuer,
+                jwks_url=self.jwks_url,
+                jwks=self.jwks,
+            )
+            if not result.ok:
+                http_status = status_from_code(result.code)
+                raise HTTPException(
+                    status_code=http_status,
+                    detail={"code": result.code, "error": result.error},
+                )
+            return AgentIdentity(email=result.email or "")
+
+        # Account resolution / provisioning
+        if self.auto_create and self.creator is not None:
+            outcome = await create_agent_account_async(
+                token=token,
+                audience=self.audience,
+                resolver=self.resolver,
+                creator=self.creator,
+                issuer=self.issuer,
+                jwks_url=self.jwks_url,
+                jwks=self.jwks,
+            )
+        else:
+            outcome = await verify_agent_account_async(
+                token=token,
+                audience=self.audience,
+                resolver=self.resolver,
+                issuer=self.issuer,
+                jwks_url=self.jwks_url,
+                jwks=self.jwks,
+            )
+
+        if not outcome.ok:
+            http_status = status_from_code(outcome.code)
+            raise HTTPException(
+                status_code=http_status,
+                detail={"code": outcome.code, "error": outcome.error},
+            )
+
+        return outcome.user  # type: ignore[return-value]

agentonboard/frameworks/flask.py

@@ -0,0 +1,124 @@
+"""
+Flask decorator and helper for AgentOnboard.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from flask import g, jsonify, request
+
+from agentonboard.account import (
+    AccountCreator,
+    AccountResolver,
+    AgentIdentity,
+    create_agent_account,
+    verify_agent_account,
+)
+from agentonboard.codes import status_from_code
+from agentonboard.verify import verify_agent_token
+
+F = TypeVar("F", bound=Callable[..., Any])
+TUser = TypeVar("TUser")
+
+
+def require_agent_token(
+    *,
+    audience: str,
+    resolver: AccountResolver[TUser] | None = None,
+    creator: AccountCreator[TUser] | None = None,
+    auto_create: bool = False,
+    issuer: str | None = None,
+    jwks_url: str | None = None,
+    jwks: dict[str, Any] | None = None,
+) -> Callable[[F], F]:
+    """
+    Flask route decorator for verifying AgentOnboard session tokens.
+
+    Usage:
+        @app.route("/protected")
+        @require_agent_token(audience="notes.com")
+        def protected():
+            return jsonify({"user": g.agent_identity.email})
+    """
+
+    def decorator(fn: F) -> F:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            auth_header = request.headers.get("Authorization", "")
+            if not auth_header or not auth_header.startswith("Bearer "):
+                return (
+                    jsonify(
+                        {
+                            "code": "MALFORMED_TOKEN",
+                            "error": "Missing or malformed Authorization Bearer header",
+                        }
+                    ),
+                    401,
+                )
+
+            token = auth_header[7:].strip()
+
+            if resolver is None:
+                res = verify_agent_token(
+                    token=token,
+                    audience=audience,
+                    issuer=issuer,
+                    jwks_url=jwks_url,
+                    jwks=jwks,
+                )
+                if not res.ok:
+                    status_code = status_from_code(res.code)
+                    return jsonify({"code": res.code, "error": res.error}), status_code
+
+                identity = AgentIdentity(email=res.email or "")
+                g.agent_identity = identity
+
+                sig = inspect.signature(fn)
+                if "agent_identity" in sig.parameters:
+                    kwargs["agent_identity"] = identity
+                return fn(*args, **kwargs)
+
+            # Account resolution
+            if auto_create and creator is not None:
+                outcome = create_agent_account(
+                    token=token,
+                    audience=audience,
+                    resolver=resolver,
+                    creator=creator,
+                    issuer=issuer,
+                    jwks_url=jwks_url,
+                    jwks=jwks,
+                )
+            else:
+                outcome = verify_agent_account(
+                    token=token,
+                    audience=audience,
+                    resolver=resolver,
+                    issuer=issuer,
+                    jwks_url=jwks_url,
+                    jwks=jwks,
+                )
+
+            if not outcome.ok:
+                status_code = status_from_code(outcome.code)
+                return jsonify({"code": outcome.code, "error": outcome.error}), status_code
+
+            identity = AgentIdentity(email=outcome.email or "")
+            g.agent_identity = identity
+            g.agent_user = outcome.user
+
+            sig = inspect.signature(fn)
+            if "agent_user" in sig.parameters:
+                kwargs["agent_user"] = outcome.user
+            if "agent_identity" in sig.parameters:
+                kwargs["agent_identity"] = identity
+
+            return fn(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator