legant-sdk 0.1.0__tar.gz

legant_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: legant-sdk
+Version: 0.1.0
+Summary: Offline verifier + authorizer for Legant delegation tokens (RFC 8693 sub/act), with Tier-B revocation-feed support.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/legant-dev/legant/tree/main/clients/python
+Project-URL: Repository, https://github.com/legant-dev/legant
+Project-URL: Issues, https://github.com/legant-dev/legant/issues
+Keywords: legant,delegation,rfc8693,oauth2,ai-agents,mcp,authorization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=3.4
+
+# legant-sdk (Python)
+
+Offline verifier + authorizer for Legant delegation tokens. Its only dependency
+is [`cryptography`](https://pypi.org/project/cryptography/) (Python ≥ 3.9).
+
+```python
+from legant_sdk import fetch_jwks, Verifier, Action, fetch_revocation_feed
+
+issuer = "https://auth.example.com"
+keys = fetch_jwks(f"{issuer}/.well-known/jwks.json")
+
+# Tier B (optional): reject revoked tokens offline, refreshed in the background.
+feed = fetch_revocation_feed(f"{issuer}/.well-known/revoked", issuer, keys)
+feed.start_polling(10.0, on_error=print)
+
+verifier = Verifier(issuer, "https://my-api.example/", keys, feed=feed)
+
+# Per request:
+claims = verifier.verify(bearer_token)  # raises VerifyError / RevokedError on failure
+claims.authorize(Action(scope="expenses:submit", amount=120, category="travel"))  # raises AuthorizeError on 403
+print(claims.provenance())  # "user:alice -> agent:assistant"
+```
+
+`verify` raises `VerifyError` (or `RevokedError` when the token is in the feed);
+`authorize` raises `AuthorizeError` when a scope or constraint is denied. Catch
+them to return 401 / 403.
+
+## Guard an agent's tools — any framework
+
+`AgentGuard` wraps any tool callable so every invocation is authorized against
+the agent's delegation token — offline, no callback. The wrapped function is a
+plain callable, so it drops into LangChain, CrewAI, LlamaIndex, AutoGen, or your
+own loop unchanged. A prompt-injected or buggy agent cannot exceed the scoped,
+revocable slice the token carries.
+
+```python
+from legant_sdk import Verifier, AgentGuard
+
+verifier = Verifier(issuer, "https://my-api.example/", keys, feed=feed)
+guard = AgentGuard(verifier, token=agent_delegation_token)  # token may be a callable, to refresh
+
+@guard.tool("expenses:submit", amount_arg="amount", category_arg="category")
+def submit_expense(amount: float, category: str) -> str:
+    ...  # only runs if the token permits this scope, amount, and category — else AuthorizeError
+
+# LangChain: from langchain_core.tools import tool;  lc_tool = tool(submit_expense)
+# CrewAI:    @tool("Submit expense")  def submit_expense(...): ...  then wrap with @guard.tool(...)
+```
+
+Or check inline without the decorator: `guard.authorize("scope", amount=…)` (raises)
+or `guard.allowed("scope", amount=…)` (returns a bool).
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests    # runs the shared conformance vectors (see ../conformance)
+```

legant_sdk-0.1.0/README.md

@@ -0,0 +1,57 @@
+# legant-sdk (Python)
+
+Offline verifier + authorizer for Legant delegation tokens. Its only dependency
+is [`cryptography`](https://pypi.org/project/cryptography/) (Python ≥ 3.9).
+
+```python
+from legant_sdk import fetch_jwks, Verifier, Action, fetch_revocation_feed
+
+issuer = "https://auth.example.com"
+keys = fetch_jwks(f"{issuer}/.well-known/jwks.json")
+
+# Tier B (optional): reject revoked tokens offline, refreshed in the background.
+feed = fetch_revocation_feed(f"{issuer}/.well-known/revoked", issuer, keys)
+feed.start_polling(10.0, on_error=print)
+
+verifier = Verifier(issuer, "https://my-api.example/", keys, feed=feed)
+
+# Per request:
+claims = verifier.verify(bearer_token)  # raises VerifyError / RevokedError on failure
+claims.authorize(Action(scope="expenses:submit", amount=120, category="travel"))  # raises AuthorizeError on 403
+print(claims.provenance())  # "user:alice -> agent:assistant"
+```
+
+`verify` raises `VerifyError` (or `RevokedError` when the token is in the feed);
+`authorize` raises `AuthorizeError` when a scope or constraint is denied. Catch
+them to return 401 / 403.
+
+## Guard an agent's tools — any framework
+
+`AgentGuard` wraps any tool callable so every invocation is authorized against
+the agent's delegation token — offline, no callback. The wrapped function is a
+plain callable, so it drops into LangChain, CrewAI, LlamaIndex, AutoGen, or your
+own loop unchanged. A prompt-injected or buggy agent cannot exceed the scoped,
+revocable slice the token carries.
+
+```python
+from legant_sdk import Verifier, AgentGuard
+
+verifier = Verifier(issuer, "https://my-api.example/", keys, feed=feed)
+guard = AgentGuard(verifier, token=agent_delegation_token)  # token may be a callable, to refresh
+
+@guard.tool("expenses:submit", amount_arg="amount", category_arg="category")
+def submit_expense(amount: float, category: str) -> str:
+    ...  # only runs if the token permits this scope, amount, and category — else AuthorizeError
+
+# LangChain: from langchain_core.tools import tool;  lc_tool = tool(submit_expense)
+# CrewAI:    @tool("Submit expense")  def submit_expense(...): ...  then wrap with @guard.tool(...)
+```
+
+Or check inline without the decorator: `guard.authorize("scope", amount=…)` (raises)
+or `guard.allowed("scope", amount=…)` (returns a bool).
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests    # runs the shared conformance vectors (see ../conformance)
+```

legant_sdk-0.1.0/legant_sdk/__init__.py

@@ -0,0 +1,40 @@
+"""Legant SDK — offline verification and authorization of delegation tokens."""
+
+from .agentguard import AgentGuard
+from .middleware import (
+    authenticate,
+    bearer_token,
+    fastapi_auth,
+    flask_require,
+    mcp_tool_name,
+)
+from .revocation import RevocationFeed, fetch_revocation_feed
+from .verifier import (
+    Action,
+    AuthorizeError,
+    Claims,
+    RevokedError,
+    Verifier,
+    VerifyError,
+    fetch_jwks,
+    parse_jwks,
+)
+
+__all__ = [
+    "Verifier",
+    "Claims",
+    "Action",
+    "AgentGuard",
+    "VerifyError",
+    "AuthorizeError",
+    "RevokedError",
+    "parse_jwks",
+    "fetch_jwks",
+    "RevocationFeed",
+    "fetch_revocation_feed",
+    "authenticate",
+    "bearer_token",
+    "fastapi_auth",
+    "flask_require",
+    "mcp_tool_name",
+]

legant_sdk-0.1.0/legant_sdk/agentguard.py

@@ -0,0 +1,101 @@
+"""Framework-agnostic tool authorization for AI agents.
+
+Wrap any tool callable — a LangChain ``@tool``, a CrewAI / LlamaIndex / AutoGen
+tool, or a plain function — so every invocation is authorized against a Legant
+delegation token, offline, with no callback. The agent only ever wields the
+scoped, attenuating, revocable slice of authority the token carries; a
+prompt-injected or buggy agent physically cannot exceed it.
+
+    guard = AgentGuard(verifier, token="<the agent's delegation token>")
+
+    @guard.tool("expenses:submit", amount_arg="amount", category_arg="category")
+    def submit_expense(amount: float, category: str) -> str:
+        ...   # only runs if the token permits this scope, amount, and category
+
+These wrappers are plain callables, so they drop into any framework that takes a
+function as a tool. ``token`` may also be a zero-arg callable, so it can be
+refreshed (re-exchanged) without rebuilding the guard.
+"""
+
+from __future__ import annotations
+
+import functools
+from datetime import datetime
+from typing import Callable, Optional, Union
+
+from .verifier import Action, Claims, Verifier
+
+TokenSource = Union[str, Callable[[], str]]
+
+
+class AgentGuard:
+    """Authorizes an agent's tool calls against a Legant delegation token."""
+
+    def __init__(self, verifier: Verifier, token: TokenSource):
+        self._verifier = verifier
+        self._token = token
+
+    def _current_token(self) -> str:
+        return self._token() if callable(self._token) else self._token
+
+    def authorize(
+        self,
+        scope: str,
+        *,
+        amount: float = 0.0,
+        category: str = "",
+        tool: str = "",
+        resource: str = "",
+        at: Optional[datetime] = None,
+    ) -> Claims:
+        """Verify the current token and authorize one action.
+
+        Raises ``VerifyError`` / ``RevokedError`` if the token is invalid or
+        revoked, or ``AuthorizeError`` if the action exceeds the delegation.
+        Returns the verified :class:`Claims` (whose ``provenance()`` you can log).
+        """
+        claims = self._verifier.verify(self._current_token())
+        claims.authorize(
+            Action(scope=scope, amount=amount, category=category, tool=tool, resource=resource, at=at)
+        )
+        return claims
+
+    def allowed(self, scope: str, **kwargs) -> bool:
+        """Non-raising check — True iff :meth:`authorize` would succeed."""
+        try:
+            self.authorize(scope, **kwargs)
+            return True
+        except Exception:
+            return False
+
+    def tool(
+        self,
+        scope: str,
+        *,
+        tool: str = "",
+        resource: str = "",
+        amount_arg: Optional[str] = None,
+        category_arg: Optional[str] = None,
+    ) -> Callable[[Callable], Callable]:
+        """Decorator that authorizes the wrapped tool before it runs.
+
+        ``amount_arg`` / ``category_arg`` name the wrapped function's keyword
+        arguments to read the monetary amount / category from, so constraint
+        checks (max-amount, category allow-list) use the real call values.
+        ``tool`` / ``resource`` are the Legant tool-constraint and resource-audience
+        values to check (each defaults to empty = not constrained by that
+        dimension).
+        """
+
+        def deco(fn: Callable) -> Callable:
+            @functools.wraps(fn)
+            def wrapper(*args, **kwargs):
+                amount = float(kwargs.get(amount_arg, 0) or 0) if amount_arg else 0.0
+                category = str(kwargs.get(category_arg, "") or "") if category_arg else ""
+                self.authorize(scope, amount=amount, category=category, tool=tool, resource=resource)
+                return fn(*args, **kwargs)
+
+            wrapper.__legant_guarded__ = True  # type: ignore[attr-defined]
+            return wrapper
+
+        return deco

legant_sdk-0.1.0/legant_sdk/middleware.py

@@ -0,0 +1,151 @@
+"""Resource-server middleware for FastAPI and Flask.
+
+A backend becomes a Legant-protected resource server in a few lines: verify the
+Bearer token, expose the verified ``Claims``, and (optionally) authorize a
+per-request ``Action``. This is the delegation-aware analog of a generic OIDC JWT
+dependency — it understands the ``act`` chain, the constraint dimensions, RFC 8707
+audience canonicalization, and the signed revocation feed.
+
+FastAPI and Flask are NOT dependencies of this package; they are imported lazily
+inside the factory functions, so ``import legant_sdk`` works without either.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Callable, Optional, Union
+
+from .verifier import Action, AuthorizeError, Claims, Verifier, VerifyError
+
+# An action can be a fixed Action, a callable deriving one from the request, or None.
+ActionSpec = Union[Action, Callable[..., Action], None]
+
+
+def bearer_token(authorization: Optional[str]) -> str:
+    """Extract the token from an ``Authorization: Bearer <token>`` header value."""
+    if not authorization:
+        raise VerifyError("missing Authorization header")
+    parts = authorization.strip().split(None, 1)
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        raise VerifyError("Authorization header is not a Bearer token")
+    return parts[1].strip()
+
+
+def authenticate(verifier: Verifier, authorization: Optional[str]) -> Claims:
+    """Verify the Bearer token from an Authorization header value (raises on failure)."""
+    return verifier.verify(bearer_token(authorization))
+
+
+def _resolve_action(spec: ActionSpec, scope: Optional[str], request) -> Optional[Action]:
+    if scope is not None:
+        return Action(scope=scope)
+    if spec is None:
+        return None
+    if callable(spec):
+        return spec(request)
+    return spec
+
+
+# ---- FastAPI ---------------------------------------------------------------
+
+
+def fastapi_auth(
+    verifier: Verifier,
+    *,
+    scope: Optional[str] = None,
+    action: ActionSpec = None,
+):
+    """Return a FastAPI dependency that verifies the Bearer token (and optionally
+    authorizes ``scope`` or ``action``), yielding the verified ``Claims``.
+
+        claims_dep = fastapi_auth(verifier, scope="data:read")
+
+        @app.get("/data")
+        def read(claims: Claims = Depends(claims_dep)):
+            ...
+
+    ``action`` may be a fixed ``Action`` or ``callable(request) -> Action`` for
+    per-request constraints (amount/resource/tool/time).
+    """
+    from fastapi import HTTPException, Request  # lazy import
+
+    def dependency(request: Request) -> Claims:
+        try:
+            claims = authenticate(verifier, request.headers.get("authorization"))
+        except VerifyError as e:
+            raise HTTPException(
+                status_code=401, detail=str(e), headers={"WWW-Authenticate": "Bearer"}
+            )
+        act = _resolve_action(action, scope, request)
+        if act is not None:
+            try:
+                claims.authorize(act)
+            except AuthorizeError as e:
+                raise HTTPException(status_code=403, detail=str(e))
+        return claims
+
+    return dependency
+
+
+# ---- Flask -----------------------------------------------------------------
+
+
+def flask_require(
+    verifier: Verifier,
+    *,
+    scope: Optional[str] = None,
+    action: ActionSpec = None,
+):
+    """Return a Flask view decorator that verifies the Bearer token (and optionally
+    authorizes ``scope``/``action``), storing the ``Claims`` on ``flask.g.legant``.
+
+        @app.get("/data")
+        @flask_require(verifier, scope="data:read")
+        def read():
+            claims = flask.g.legant
+            ...
+    """
+    from functools import wraps
+
+    from flask import Response, g, request  # lazy import
+
+    def challenge(code: int, err: str, desc: str) -> "Response":
+        resp = Response(f"{err}: {desc}", status=code)
+        resp.headers["WWW-Authenticate"] = f'Bearer error="{err}", error_description="{desc}"'
+        return resp
+
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            try:
+                claims = authenticate(verifier, request.headers.get("Authorization"))
+            except VerifyError as e:
+                return challenge(401, "invalid_token", str(e))
+            act = _resolve_action(action, scope, request)
+            if act is not None:
+                try:
+                    claims.authorize(act)
+                except AuthorizeError as e:
+                    return challenge(403, "insufficient_scope", str(e))
+            g.legant = claims
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+# ---- self-hosted MCP server helper -----------------------------------------
+
+
+def mcp_tool_name(body: Union[bytes, str, dict]) -> str:
+    """Extract the tool name from a JSON-RPC MCP ``tools/call`` request body, for
+    resource servers that ARE an MCP server. Pair with ``claims.authorize``."""
+    if isinstance(body, (bytes, str)):
+        body = json.loads(body)
+    if not isinstance(body, dict) or body.get("method") != "tools/call":
+        raise ValueError(f"not a tools/call (method={body.get('method') if isinstance(body, dict) else None!r})")
+    name = (body.get("params") or {}).get("name")
+    if not name:
+        raise ValueError("tools/call missing params.name")
+    return name

legant_sdk-0.1.0/legant_sdk/revocation.py

@@ -0,0 +1,95 @@
+"""Tier B offline revocation: a pull-based view of revoked tokens.
+
+The resource server fetches a signed feed from the issuer on a timer and checks
+token ids against an in-memory set, with no per-request callback. A stale or
+missing feed can only ever MISS a revocation, never invent one, and a regressing
+version is rejected as a rollback.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.request
+from typing import Callable, Optional
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding
+
+from .verifier import _b64url
+
+
+class RevocationFeed:
+    def __init__(self, url: Optional[str], issuer: str, keys: dict) -> None:
+        self._url = url
+        self._issuer = issuer
+        self._keys = keys
+        self._revoked: set[str] = set()
+        self._version = 0
+        self._fetched_at = 0.0
+
+    def apply_feed(self, jws: str) -> None:
+        """Verifies (RS256 under the issuer's kid, issuer + expiry), enforces a
+        monotonic version, then atomically swaps the in-memory set."""
+        h, p, s = jws.split(".")
+        header = json.loads(_b64url(h))
+        if header.get("alg") != "RS256":
+            raise ValueError(f"unexpected alg {header.get('alg')}")
+        key = self._keys.get(header.get("kid"))
+        if key is None:
+            raise ValueError(f'unknown feed signing key "{header.get("kid")}"')
+        try:
+            key.verify(_b64url(s), f"{h}.{p}".encode(), padding.PKCS1v15(), hashes.SHA256())
+        except InvalidSignature:
+            raise ValueError("feed signature verification failed")
+        c = json.loads(_b64url(p))
+        if c.get("iss") != self._issuer:
+            raise ValueError("feed issuer mismatch")
+        exp = c.get("exp")
+        if exp is None or time.time() >= exp:
+            raise ValueError("feed is expired or missing exp")
+        ver = int(c.get("ver", 0))
+        if ver < self._version:
+            raise ValueError(
+                f"revocation feed version regressed ({ver} < {self._version}) — possible rollback, keeping current"
+            )
+        self._revoked = set(c.get("jtis") or [])
+        self._version = ver
+        self._fetched_at = time.time()
+
+    def refresh(self, timeout: float = 10.0) -> None:
+        if not self._url:
+            raise ValueError("revocation feed has no URL")
+        with urllib.request.urlopen(self._url, timeout=timeout) as r:  # noqa: S310 (configured URL)
+            self.apply_feed(r.read().decode())
+
+    def start_polling(self, interval_s: float, on_error: Optional[Callable[[Exception], None]] = None) -> Callable[[], None]:
+        """Refreshes on an interval in a daemon thread until the returned stop
+        function is called. Refresh errors are non-fatal."""
+        stop = threading.Event()
+
+        def loop() -> None:
+            while not stop.wait(interval_s):
+                try:
+                    self.refresh()
+                except Exception as e:  # noqa: BLE001 - non-fatal
+                    if on_error:
+                        on_error(e)
+
+        threading.Thread(target=loop, daemon=True).start()
+        return stop.set
+
+    def is_revoked(self, jti: str) -> bool:
+        return jti in self._revoked
+
+    def staleness(self) -> float:
+        """Milliseconds since the feed was last successfully applied."""
+        return (time.time() - self._fetched_at) * 1000.0
+
+
+def fetch_revocation_feed(feed_url: str, issuer: str, keys: dict) -> RevocationFeed:
+    f = RevocationFeed(feed_url, issuer, keys)
+    f.refresh()
+    return f

legant_sdk-0.1.0/legant_sdk/verifier.py

@@ -0,0 +1,248 @@
+"""Offline verifier + authorizer for Legant delegation tokens.
+
+Verifies a composite sub/act token against the issuer's JWKS and authorizes a
+request's scope and constraints, entirely offline (no callback to Legant). Its
+only dependency is ``cryptography``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional, Union
+from zoneinfo import ZoneInfo
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+
+# Sentinel Legant puts in an allow-list that intersected to nothing during
+# re-delegation. It matches no real value and denies the dimension entirely.
+# Must match internal/delegation and the Go/TS SDKs.
+_DENY_ALL = "\x00legant:deny-all"
+
+
+class VerifyError(Exception):
+    """Raised when a token fails verification."""
+
+
+class AuthorizeError(Exception):
+    """Raised when an action is not permitted by the token's scope/constraints."""
+
+
+class RevokedError(VerifyError):
+    """Raised by Verifier.verify when the token's jti is in the revocation feed."""
+
+    def __init__(self) -> None:
+        super().__init__("token revoked")
+
+
+@dataclass
+class Action:
+    scope: str
+    amount: float = 0.0
+    category: str = ""
+    tool: str = ""
+    resource: str = ""
+    at: Optional[datetime] = None  # instant of the action; None = now
+
+
+@dataclass
+class Claims:
+    raw: dict
+
+    @property
+    def subject(self) -> str:
+        return self.raw.get("sub", "")
+
+    @property
+    def jti(self) -> str:
+        return self.raw.get("jti", "")
+
+    @property
+    def scope(self) -> str:
+        return self.raw.get("scope", "")
+
+    @property
+    def constraints(self) -> Optional[dict]:
+        return self.raw.get("cnst")
+
+    def provenance(self) -> str:
+        """Renders e.g. 'user:alice -> agent:assistant -> agent:ocr'."""
+        parts = [self.raw.get("sub", "")]
+        chain = []
+        a = self.raw.get("act")
+        while a:
+            chain.append(a.get("sub", ""))
+            a = a.get("act")
+        parts.extend(reversed(chain))
+        return " -> ".join(parts)
+
+    def authorize(self, action: Action) -> None:
+        """Raises AuthorizeError if the scope is missing or a constraint is violated."""
+        if action.scope not in self.scope.split():
+            raise AuthorizeError(f'missing required scope "{action.scope}"')
+        k = self.constraints
+        if not k:
+            return
+        max_amount = k.get("max_amount")
+        if max_amount is not None and action.amount > max_amount:
+            raise AuthorizeError(f"amount {action.amount} exceeds max_amount {max_amount}")
+        _permit_list("category", k.get("categories"), action.category, canonical=False)
+        _permit_list("tool", k.get("tools"), action.tool, canonical=False)
+        _permit_list("resource", k.get("resources"), action.resource, canonical=True)
+        tw = k.get("time_window")
+        if tw:
+            at = action.at or datetime.now(timezone.utc)
+            if not _time_window_allows(tw, at):
+                raise AuthorizeError("action is outside the delegated time window")
+
+
+class Verifier:
+    def __init__(
+        self,
+        issuer: str,
+        audience: str,
+        keys: dict,
+        feed=None,
+        feed_fail_closed_ms: Optional[int] = None,
+    ) -> None:
+        self._issuer = issuer
+        self._audience = audience
+        self._keys = keys
+        self._feed = feed
+        self._feed_fail_closed_ms = feed_fail_closed_ms
+
+    def verify(self, token: str) -> Claims:
+        """Verifies RS256 signature (by kid), issuer, expiry, not-before, and
+        audience, and requires an act claim. Raises VerifyError on any failure."""
+        parts = token.split(".")
+        if len(parts) != 3:
+            raise VerifyError("malformed token")
+        h, p, s = parts
+        header = json.loads(_b64url(h))
+        if header.get("alg") != "RS256":
+            raise VerifyError(f"unexpected alg {header.get('alg')}")
+        kid = header.get("kid")
+        if not kid:
+            raise VerifyError("token missing kid header")
+        key = self._keys.get(kid)
+        if key is None:
+            raise VerifyError(f'unknown signing key "{kid}"')
+        try:
+            key.verify(_b64url(s), f"{h}.{p}".encode(), padding.PKCS1v15(), hashes.SHA256())
+        except InvalidSignature:
+            raise VerifyError("signature verification failed")
+        c = json.loads(_b64url(p))
+        if c.get("iss") != self._issuer:
+            raise VerifyError("invalid issuer")
+        now = time.time()
+        exp = c.get("exp")
+        if exp is None:
+            raise VerifyError("token has no expiration")
+        if now >= exp:
+            raise VerifyError("token is expired")
+        nbf = c.get("nbf")
+        if nbf is not None and now < nbf:
+            raise VerifyError("token is not valid yet")
+        if not c.get("act"):
+            raise VerifyError("not a delegation token (no act claim)")
+        if not _audience_matches(c.get("aud"), self._audience):
+            raise VerifyError("token audience does not include this resource server")
+        if self._feed is not None:
+            if self._feed_fail_closed_ms is not None and self._feed.staleness() > self._feed_fail_closed_ms:
+                raise VerifyError("revocation feed is stale and fail-closed is set")
+            jti = c.get("jti")
+            if jti and self._feed.is_revoked(jti):
+                raise RevokedError()
+        return Claims(c)
+
+
+def _b64url(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _permit_list(dim: str, allowed, value: str, canonical: bool) -> None:
+    if not allowed:
+        return
+    if _DENY_ALL in allowed:
+        raise AuthorizeError(f"{dim} access is fully restricted by the delegation")
+    if value == "":
+        return
+    match = value in allowed
+    if not match and canonical:
+        cv = _canonicalize_audience(value)
+        match = any(_canonicalize_audience(a) == cv for a in allowed)
+    if not match:
+        raise AuthorizeError(f'{dim} "{value}" not permitted')
+
+
+def _audience_matches(aud: Union[str, list, None], want: str) -> bool:
+    if aud is None:
+        auds = []
+    elif isinstance(aud, list):
+        auds = aud
+    else:
+        auds = [aud]
+    cw = _canonicalize_audience(want)
+    return any(_canonicalize_audience(a) == cw for a in auds)
+
+
+def _canonicalize_audience(raw: str) -> str:
+    """Mirrors the issuer's RFC 8707 canonicalization: lowercase scheme+host,
+    strip a default port, drop userinfo and fragment, empty path -> '/'.
+    Non-absolute values are returned unchanged."""
+    from urllib.parse import urlsplit, urlunsplit
+
+    u = urlsplit(raw)
+    if not u.scheme or not u.hostname:
+        return raw
+    scheme = u.scheme.lower()
+    host = u.hostname.lower()
+    port = u.port
+    if not ((scheme == "https" and port == 443) or (scheme == "http" and port == 80) or port is None):
+        host = f"{host}:{port}"
+    path = u.path if u.path else "/"
+    return urlunsplit((scheme, host, path, u.query, ""))
+
+
+_WEEKDAY_OFFSET = 1  # Python weekday(): Mon=0..Sun=6 -> Go/Legant: Sun=0..Sat=6
+
+
+def _time_window_allows(tw: dict, at: datetime) -> bool:
+    tz_name = tw.get("tz") or "UTC"
+    try:
+        tz = ZoneInfo(tz_name)
+    except Exception:
+        return False  # unknown timezone fails closed
+    local = at.astimezone(tz)
+    weekday = (local.weekday() + _WEEKDAY_OFFSET) % 7  # Sun=0 .. Sat=6
+    weekdays = tw.get("weekdays")
+    if weekdays and weekday not in weekdays:
+        return False
+    minutes = local.hour * 60 + local.minute
+    return tw.get("start_min", 0) <= minutes <= tw.get("end_min", 0)
+
+
+def parse_jwks(doc: dict) -> dict:
+    """Parses a JWKS document into a kid -> RSA public key map (RSA keys only)."""
+    out = {}
+    for k in doc.get("keys", []):
+        if k.get("kty") != "RSA" or not k.get("kid"):
+            continue
+        n = int.from_bytes(_b64url(k["n"]), "big")
+        if n.bit_length() < 2048:
+            raise ValueError(f"jwk {k['kid']}: modulus too small (want >= 2048 bits)")
+        e = int.from_bytes(_b64url(k["e"]), "big")
+        out[k["kid"]] = rsa.RSAPublicNumbers(e, n).public_key()
+    return out
+
+
+def fetch_jwks(jwks_url: str, timeout: float = 10.0) -> dict:
+    """Fetches and parses an issuer's JWKS. Pass a trusted, configured URL."""
+    with urllib.request.urlopen(jwks_url, timeout=timeout) as r:  # noqa: S310 (configured URL)
+        return parse_jwks(json.loads(r.read()))

legant_sdk-0.1.0/legant_sdk.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: legant-sdk
+Version: 0.1.0
+Summary: Offline verifier + authorizer for Legant delegation tokens (RFC 8693 sub/act), with Tier-B revocation-feed support.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/legant-dev/legant/tree/main/clients/python
+Project-URL: Repository, https://github.com/legant-dev/legant
+Project-URL: Issues, https://github.com/legant-dev/legant/issues
+Keywords: legant,delegation,rfc8693,oauth2,ai-agents,mcp,authorization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=3.4
+
+# legant-sdk (Python)
+
+Offline verifier + authorizer for Legant delegation tokens. Its only dependency
+is [`cryptography`](https://pypi.org/project/cryptography/) (Python ≥ 3.9).
+
+```python
+from legant_sdk import fetch_jwks, Verifier, Action, fetch_revocation_feed
+
+issuer = "https://auth.example.com"
+keys = fetch_jwks(f"{issuer}/.well-known/jwks.json")
+
+# Tier B (optional): reject revoked tokens offline, refreshed in the background.
+feed = fetch_revocation_feed(f"{issuer}/.well-known/revoked", issuer, keys)
+feed.start_polling(10.0, on_error=print)
+
+verifier = Verifier(issuer, "https://my-api.example/", keys, feed=feed)
+
+# Per request:
+claims = verifier.verify(bearer_token)  # raises VerifyError / RevokedError on failure
+claims.authorize(Action(scope="expenses:submit", amount=120, category="travel"))  # raises AuthorizeError on 403
+print(claims.provenance())  # "user:alice -> agent:assistant"
+```
+
+`verify` raises `VerifyError` (or `RevokedError` when the token is in the feed);
+`authorize` raises `AuthorizeError` when a scope or constraint is denied. Catch
+them to return 401 / 403.
+
+## Guard an agent's tools — any framework
+
+`AgentGuard` wraps any tool callable so every invocation is authorized against
+the agent's delegation token — offline, no callback. The wrapped function is a
+plain callable, so it drops into LangChain, CrewAI, LlamaIndex, AutoGen, or your
+own loop unchanged. A prompt-injected or buggy agent cannot exceed the scoped,
+revocable slice the token carries.
+
+```python
+from legant_sdk import Verifier, AgentGuard
+
+verifier = Verifier(issuer, "https://my-api.example/", keys, feed=feed)
+guard = AgentGuard(verifier, token=agent_delegation_token)  # token may be a callable, to refresh
+
+@guard.tool("expenses:submit", amount_arg="amount", category_arg="category")
+def submit_expense(amount: float, category: str) -> str:
+    ...  # only runs if the token permits this scope, amount, and category — else AuthorizeError
+
+# LangChain: from langchain_core.tools import tool;  lc_tool = tool(submit_expense)
+# CrewAI:    @tool("Submit expense")  def submit_expense(...): ...  then wrap with @guard.tool(...)
+```
+
+Or check inline without the decorator: `guard.authorize("scope", amount=…)` (raises)
+or `guard.allowed("scope", amount=…)` (returns a bool).
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests    # runs the shared conformance vectors (see ../conformance)
+```

legant_sdk-0.1.0/legant_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+legant_sdk/__init__.py
+legant_sdk/agentguard.py
+legant_sdk/middleware.py
+legant_sdk/revocation.py
+legant_sdk/verifier.py
+legant_sdk.egg-info/PKG-INFO
+legant_sdk.egg-info/SOURCES.txt
+legant_sdk.egg-info/dependency_links.txt
+legant_sdk.egg-info/requires.txt
+legant_sdk.egg-info/top_level.txt
+tests/test_agentguard.py
+tests/test_conformance.py
+tests/test_middleware.py

legant_sdk-0.1.0/legant_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

legant_sdk-0.1.0/legant_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=3.4

legant_sdk-0.1.0/legant_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+legant_sdk

legant_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "legant-sdk"
+version = "0.1.0"
+description = "Offline verifier + authorizer for Legant delegation tokens (RFC 8693 sub/act), with Tier-B revocation-feed support."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+dependencies = ["cryptography>=3.4"]
+keywords = ["legant", "delegation", "rfc8693", "oauth2", "ai-agents", "mcp", "authorization"]
+
+[project.urls]
+Homepage = "https://github.com/legant-dev/legant/tree/main/clients/python"
+Repository = "https://github.com/legant-dev/legant"
+Issues = "https://github.com/legant-dev/legant/issues"
+
+[tool.setuptools.packages.find]
+include = ["legant_sdk*"]

legant_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

legant_sdk-0.1.0/tests/test_agentguard.py

@@ -0,0 +1,69 @@
+"""AgentGuard runs the same conformance authorize vectors through the
+framework-agnostic tool wrapper, so the agent-facing adapter can't drift from the
+SDK's authorization. From clients/python:
+
+    python3 -m unittest discover -s tests
+"""
+
+import json
+import unittest
+from datetime import datetime
+from pathlib import Path
+
+from legant_sdk import AgentGuard, AuthorizeError, Verifier, parse_jwks
+
+_VECTORS = json.loads((Path(__file__).resolve().parents[2] / "conformance" / "vectors.json").read_text())
+_KEYS = parse_jwks(_VECTORS["jwks"])
+
+
+def _guard(token: str) -> AgentGuard:
+    return AgentGuard(Verifier(_VECTORS["issuer"], _VECTORS["audience"], _KEYS), token)
+
+
+class TestAgentGuard(unittest.TestCase):
+    def test_authorize_vectors(self):
+        for c in _VECTORS["authorize"]:
+            with self.subTest(c["name"]):
+                g = _guard(c["token"])
+                a = c["action"]
+                at = datetime.fromisoformat(a["at"].replace("Z", "+00:00")) if a.get("at") else None
+                ok = g.allowed(
+                    a["scope"],
+                    amount=a.get("amount", 0),
+                    category=a.get("category", ""),
+                    tool=a.get("tool", ""),
+                    resource=a.get("resource", ""),
+                    at=at,
+                )
+                self.assertEqual(ok, c["allow"])
+
+    def test_tool_decorator_enforces(self):
+        # Find a vector that allows expenses:submit and one that denies on amount.
+        allow = next(c for c in _VECTORS["authorize"] if c["allow"] and c["action"]["scope"] == "expenses:submit")
+        deny = next(c for c in _VECTORS["authorize"] if not c["allow"] and "amount" in c["action"])
+        calls = []
+
+        def make_tool(guard):
+            @guard.tool("expenses:submit", amount_arg="amount", category_arg="category")
+            def submit_expense(amount=0.0, category=""):
+                calls.append((amount, category))
+                return "submitted"
+
+            return submit_expense
+
+        # Allowed call runs the underlying function.
+        t = make_tool(_guard(allow["token"]))
+        a = allow["action"]
+        self.assertEqual(t(amount=a.get("amount", 0), category=a.get("category", "")), "submitted")
+        self.assertEqual(len(calls), 1)
+
+        # Denied call raises BEFORE the function body runs (no new entry in calls).
+        t2 = make_tool(_guard(deny["token"]))
+        d = deny["action"]
+        with self.assertRaises(AuthorizeError):
+            t2(amount=d.get("amount", 0), category=d.get("category", ""))
+        self.assertEqual(len(calls), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

legant_sdk-0.1.0/tests/test_conformance.py

@@ -0,0 +1,87 @@
+"""Runs the shared golden vectors (clients/conformance/vectors.json, minted by the
+real Go signer) through the Python SDK. Identical assertions run against the Go
+and TypeScript SDKs, so the three cannot drift. From clients/python:
+
+    python3 -m unittest discover -s tests
+"""
+
+import json
+import unittest
+from datetime import datetime
+from pathlib import Path
+
+from legant_sdk import Action, RevocationFeed, RevokedError, Verifier, parse_jwks
+
+_VECTORS = json.loads((Path(__file__).resolve().parents[2] / "conformance" / "vectors.json").read_text())
+_KEYS = parse_jwks(_VECTORS["jwks"])
+
+
+class TestConformance(unittest.TestCase):
+    def test_verify_vectors(self):
+        ver = Verifier(_VECTORS["issuer"], _VECTORS["audience"], _KEYS)
+        for c in _VECTORS["verify"]:
+            with self.subTest(c["name"]):
+                if c["valid"]:
+                    claims = ver.verify(c["token"])
+                    if c.get("provenance"):
+                        self.assertEqual(claims.provenance(), c["provenance"])
+                else:
+                    with self.assertRaises(Exception):
+                        ver.verify(c["token"])
+
+    def test_audience_vectors(self):
+        for c in _VECTORS["audienceCanonicalization"]:
+            with self.subTest(c["name"]):
+                ver = Verifier(_VECTORS["issuer"], c["configuredAudience"], _KEYS)
+                if c["valid"]:
+                    ver.verify(c["token"])  # must not raise
+                else:
+                    with self.assertRaises(Exception):
+                        ver.verify(c["token"])
+
+    def test_authorize_vectors(self):
+        ver = Verifier(_VECTORS["issuer"], _VECTORS["audience"], _KEYS)
+        for c in _VECTORS["authorize"]:
+            with self.subTest(c["name"]):
+                claims = ver.verify(c["token"])
+                a = c["action"]
+                at = datetime.fromisoformat(a["at"].replace("Z", "+00:00")) if a.get("at") else None
+                action = Action(
+                    scope=a.get("scope", ""),
+                    amount=a.get("amount", 0.0),
+                    category=a.get("category", ""),
+                    tool=a.get("tool", ""),
+                    resource=a.get("resource", ""),
+                    at=at,
+                )
+                allowed = True
+                try:
+                    claims.authorize(action)
+                except Exception:
+                    allowed = False
+                self.assertEqual(allowed, c["allow"])
+
+    def test_revocation_vectors(self):
+        r = _VECTORS["revocation"]
+        feed = RevocationFeed(None, _VECTORS["issuer"], _KEYS)
+        feed.apply_feed(r["feed"])
+        self.assertTrue(feed.is_revoked(r["revokedJti"]))
+        self.assertFalse(feed.is_revoked(r["liveJti"]))
+
+        ver = Verifier(_VECTORS["issuer"], _VECTORS["audience"], _KEYS, feed=feed)
+        with self.assertRaises(RevokedError):
+            ver.verify(r["revokedToken"])
+        ver.verify(r["liveToken"])  # live token verifies
+
+        # A rollback (lower version) is rejected; revocation persists.
+        with self.assertRaises(ValueError):
+            feed.apply_feed(r["feedRollback"])
+        self.assertTrue(feed.is_revoked(r["revokedJti"]))
+
+        # A newer feed dropping the jti clears the revocation.
+        feed.apply_feed(r["feedNewer"])
+        self.assertFalse(feed.is_revoked(r["revokedJti"]))
+
+
+if __name__ == "__main__":
+    unittest.main()

legant_sdk-0.1.0/tests/test_middleware.py

@@ -0,0 +1,124 @@
+"""Exercises the resource-server middleware against the shared golden vectors.
+The framework-agnostic core always runs; the FastAPI/Flask adapters run only when
+the framework is installed. From clients/python:
+
+    python3 -m unittest discover -s tests
+"""
+
+import json
+import unittest
+from pathlib import Path
+
+from legant_sdk import (
+    Verifier,
+    VerifyError,
+    authenticate,
+    bearer_token,
+    mcp_tool_name,
+    parse_jwks,
+)
+
+_VECTORS = json.loads((Path(__file__).resolve().parents[2] / "conformance" / "vectors.json").read_text())
+_KEYS = parse_jwks(_VECTORS["jwks"])
+_VALID = next(c["token"] for c in _VECTORS["verify"] if c["valid"])
+_ALLOW = next(c for c in _VECTORS["authorize"] if c["allow"])
+_DENY = next(c for c in _VECTORS["authorize"] if not c["allow"])
+
+
+def _verifier() -> Verifier:
+    return Verifier(_VECTORS["issuer"], _VECTORS["audience"], _KEYS)
+
+
+class TestCore(unittest.TestCase):
+    def test_bearer_token(self):
+        self.assertEqual(bearer_token("Bearer abc.def.ghi"), "abc.def.ghi")
+        with self.assertRaises(VerifyError):
+            bearer_token(None)
+        with self.assertRaises(VerifyError):
+            bearer_token("Basic xyz")
+
+    def test_authenticate(self):
+        claims = authenticate(_verifier(), f"Bearer {_VALID}")
+        self.assertTrue(claims.subject)
+        with self.assertRaises(VerifyError):
+            authenticate(_verifier(), "Bearer not-a-jwt")
+
+    def test_mcp_tool_name(self):
+        self.assertEqual(
+            mcp_tool_name({"method": "tools/call", "params": {"name": "kubectl_scale"}}),
+            "kubectl_scale",
+        )
+        self.assertEqual(mcp_tool_name('{"method":"tools/call","params":{"name":"x"}}'), "x")
+        with self.assertRaises(ValueError):
+            mcp_tool_name({"method": "tools/list"})
+
+
+class TestFlask(unittest.TestCase):
+    def setUp(self):
+        try:
+            from flask import Flask, g, jsonify
+        except ImportError:  # pragma: no cover
+            self.skipTest("flask not installed")
+        from legant_sdk import flask_require
+
+        app = Flask(__name__)
+
+        def action_from(_req):
+            from legant_sdk import Action
+
+            a = _DENY["action"]
+            return Action(scope=a["scope"], amount=a.get("amount", 0))
+
+        @app.get("/scoped")
+        @flask_require(_verifier())
+        def scoped():
+            return jsonify(sub=g.legant.subject)
+
+        @app.get("/denied")
+        @flask_require(_verifier(), action=action_from)
+        def denied():
+            return jsonify(ok=True)
+
+        self.client = app.test_client()
+
+    def test_no_token_401(self):
+        r = self.client.get("/scoped")
+        self.assertEqual(r.status_code, 401)
+        self.assertIn("Bearer", r.headers.get("WWW-Authenticate", ""))
+
+    def test_valid_token_ok(self):
+        r = self.client.get("/scoped", headers={"Authorization": f"Bearer {_VALID}"})
+        self.assertEqual(r.status_code, 200)
+
+    def test_denied_action_403(self):
+        r = self.client.get("/denied", headers={"Authorization": f"Bearer {_DENY['token']}"})
+        self.assertEqual(r.status_code, 403)
+
+
+class TestFastAPI(unittest.TestCase):
+    def setUp(self):
+        try:
+            from fastapi import Depends, FastAPI
+            from fastapi.testclient import TestClient
+        except ImportError:
+            self.skipTest("fastapi not installed")
+        from legant_sdk import Claims, fastapi_auth
+
+        app = FastAPI()
+
+        @app.get("/scoped")
+        def scoped(claims: Claims = Depends(fastapi_auth(_verifier()))):
+            return {"sub": claims.subject}
+
+        self.client = TestClient(app)
+
+    def test_no_token_401(self):
+        self.assertEqual(self.client.get("/scoped").status_code, 401)
+
+    def test_valid_token_ok(self):
+        r = self.client.get("/scoped", headers={"Authorization": f"Bearer {_VALID}"})
+        self.assertEqual(r.status_code, 200)
+
+
+if __name__ == "__main__":
+    unittest.main()