agent-identity-protocol 0.1.0__py3-none-any.whl

agent_identity_protocol-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: agent-identity-protocol
+Version: 0.1.0
+Summary: Verifiable cryptographic identity and delegation for AI agents across MCP and A2A
+Project-URL: Homepage, https://github.com/sunilp/aip
+Project-URL: Documentation, https://github.com/sunilp/aip/blob/main/docs/quickstart.md
+Project-URL: Repository, https://github.com/sunilp/aip
+Author-email: Sunil Prakash <sunil@sunilprakash.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: base58>=2.1
+Requires-Dist: biscuit-python>=0.4
+Requires-Dist: cryptography>=43.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyjwt[crypto]>=2.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Agent Identity Protocol (AIP)
+
+Verifiable, delegable identity for AI agents across MCP and A2A.
+
+AIP gives every agent a cryptographic identity that flows across protocol boundaries. A single token answers: who authorized this, through which agents, with what scope at each hop, and what was the outcome. No blockchain, no wallet UX -- just Ed25519 keys and append-only token chains.
+
+## Why AIP
+
+- MCP has no authentication layer. A2A has self-declared identities with no attestation.
+- When Agent A delegates to Agent B, no identity verification happens.
+- No existing protocol combines identity, delegation, and provenance in a single verifiable artifact.
+
+AIP fills this gap.
+
+## Quick Start (Python)
+
+```bash
+pip install -e python/
+```
+
+```python
+from aip_core.crypto import KeyPair
+from aip_token.claims import AipClaims
+from aip_token.compact import CompactToken
+import time
+
+# Generate identity
+kp = KeyPair.generate()
+
+# Create a compact token for MCP tool access
+claims = AipClaims(
+    iss="aip:key:ed25519:" + kp.public_key_multibase(),
+    sub="aip:web:example.com/tools/search",
+    scope=["tool:search"],
+    budget_usd=1.0,
+    max_depth=0,
+    iat=int(time.time()),
+    exp=int(time.time()) + 3600,
+)
+token = CompactToken.create(claims, kp)
+
+# Send to MCP server
+headers = {"X-AIP-Token": token}
+```
+
+## Multi-Agent Delegation
+
+When agents delegate to other agents, each hop cryptographically narrows scope:
+
+```python
+from aip_token.chained import ChainedToken
+
+root_kp = KeyPair.generate()
+
+# Orchestrator: broad authority
+token = ChainedToken.create_authority(
+    issuer="aip:web:myorg.com/orchestrator",
+    scopes=["tool:search", "tool:email"],
+    budget_cents=500,
+    max_depth=3,
+    ttl_seconds=3600,
+    keypair=root_kp,
+)
+
+# Delegate to specialist: only search, lower budget
+delegated = token.delegate(
+    delegator="aip:web:myorg.com/orchestrator",
+    delegate="aip:web:myorg.com/specialist",
+    scopes=["tool:search"],
+    budget_cents=100,
+    context="research task for user query",
+)
+
+# Specialist verifies before calling tool
+delegated.authorize("tool:search", root_kp.public_key_bytes())  # passes
+delegated.authorize("tool:email", root_kp.public_key_bytes())   # raises -- attenuated away
+```
+
+## Two Token Modes
+
+**Compact** (JWT + EdDSA) -- single hop, drop-in for existing MCP servers. Standard JWT libraries can verify.
+
+**Chained** (Biscuit) -- multi-hop delegation with append-only blocks. Each block can only narrow scope, never widen. Datalog policy evaluation at each hop.
+
+Start with compact. Upgrade to chained when you need delegation. Same identity scheme, same protocol bindings.
+
+## Features
+
+- DNS-based (`aip:web:`) and self-certifying (`aip:key:`) identity schemes
+- Ed25519 cryptography, no algorithm negotiation
+- MCP, A2A, and HTTP protocol bindings
+- MCP middleware for token verification
+- Delegation chains with cryptographic scope attenuation
+- Budget tracking in integer cents
+- Policy profiles: Simple (templated), Standard (curated Datalog), Advanced (full Datalog)
+- Identity document self-signatures (protects against domain compromise)
+
+## Installation
+
+### Python (primary SDK)
+
+```bash
+cd python
+pip install -e ".[dev]"
+```
+
+### Rust (reference implementation)
+
+```toml
+[dependencies]
+aip-core = { path = "rust/aip-core" }
+aip-token = { path = "rust/aip-token" }
+aip-mcp = { path = "rust/aip-mcp" }
+```
+
+## Tests
+
+```bash
+# Python
+cd python && pytest tests/ -v
+
+# Rust
+cd rust && cargo test
+
+# Cross-language interop
+python -m pytest tests/conformance/ -v
+```
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md) -- 5 minutes to your first AIP token
+- [Delegation guide](docs/guide-delegation.md) -- chained tokens, scope attenuation, policy profiles
+- [Competitive analysis](docs/competitive-analysis.md) -- AIP vs OAuth, DID, UCAN, Macaroons, Biscuit, SPIFFE
+- [Specification](SPEC.md) -- full protocol spec
+
+## Examples
+
+- [Single-agent MCP](examples/single-agent-mcp/) -- agent authenticates to MCP tool server
+- [Multi-agent delegation](examples/multi-agent-delegation/) -- orchestrator delegates to specialist, calls tool server
+
+## Paper
+
+The protocol design, experiments, and adversarial evaluation are described in:
+
+> Sunil Prakash. **AIP: Agent Identity Protocol for Verifiable Delegation Across MCP and A2A.** arXiv preprint arXiv:2603.24775, 2026.
+> [https://arxiv.org/abs/2603.24775](https://arxiv.org/abs/2603.24775)
+
+### Citing
+
+```bibtex
+@article{prakash2026aip,
+  title={AIP: Agent Identity Protocol for Verifiable Delegation Across MCP and A2A},
+  author={Prakash, Sunil},
+  journal={arXiv preprint arXiv:2603.24775},
+  year={2026}
+}
+```
+
+### Related Papers
+
+AIP is part of a multi-agent trust stack. Each paper addresses a different layer:
+
+| Layer | Paper | arXiv |
+|-------|-------|-------|
+| **Identity** | AIP: Verifiable Delegation Across MCP and A2A | [2603.24775](https://arxiv.org/abs/2603.24775) |
+| **Provenance** | The Provenance Paradox in Multi-Agent LLM Routing | [2603.18043](https://arxiv.org/abs/2603.18043) |
+| **Protocol** | LDP: An Identity-Aware Protocol for Multi-Agent LLM Systems | [2603.08852](https://arxiv.org/abs/2603.08852) |
+| **Reasoning** | DCI: Structured Collective Reasoning with Typed Epistemic Acts | [2603.11781](https://arxiv.org/abs/2603.11781) |
+
+## License
+
+Apache 2.0

agent_identity_protocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+aip_core/__init__.py,sha256=JTy34CK9oA_SGn69PqiprPWa2I8YffCTzGqYuQyBjf4,283
+aip_core/crypto.py,sha256=ByK7QMLPXU2iFVR267rSs_m4DhOXx7DoGQuRK7gBxF0,2287
+aip_core/document.py,sha256=XXY1Bxk2enfme5ziNHlc_IIyAu8ITVs4OYXWiW-wR3E,4230
+aip_core/error.py,sha256=GGiYW_T-gYic19lsI4jVz9JpCO0mORIuskFU12f6KcQ,262
+aip_core/identity.py,sha256=Ms-LoXxgRI19V-iVs_dTvlQl-hN4ihCgewStks98B2I,2888
+aip_mcp/__init__.py,sha256=OhVdl2jTyCAzfVkR4PwzpZHHLItLHONO5cYrbufltcs,119
+aip_mcp/error.py,sha256=oaWkLSsDKM36wVj519a7sExPdwlvhxffIxX8GF5XFd4,725
+aip_mcp/middleware.py,sha256=WoqMo4u-6shUSeqO1TyfG_KZrireElC2k2FeFaiX84s,1890
+aip_token/__init__.py,sha256=u3BfKbRbopAp3MyVnjMWA4atA02Lt_tCxZIzolesIdg,568
+aip_token/chained.py,sha256=2-0L_eY1BQJj9WIYL2xJUmzlOunAeFCRSqmO9eU09Sg,7029
+aip_token/claims.py,sha256=1inWQBgryNP0-L5RXPzYd-9esryOjpXrTw4XYHZaGqQ,634
+aip_token/compact.py,sha256=F0_AJ49e7d5FbM_cdb0hDzIrl9Qgmp306B9gQ1ZFngs,2518
+aip_token/delegation.py,sha256=S3u6Lkgc9FUvl4jhM-1HXdllelc7QjavD0LMopwIZZ4,344
+aip_token/error.py,sha256=PfLT71IMhX_GowtonQUvATPqeSQOAr--fMYACPciwwU,1830
+aip_token/policy.py,sha256=nZGbeJ3n-zPyZ1k1Py7GbhXKVFEIhtU4Bp4zuu9hwjk,1283
+agent_identity_protocol-0.1.0.dist-info/METADATA,sha256=V58PZXtLXsCYptBMauRT-Sb0fZbkQWEZm0hXwcIRmPo,6411
+agent_identity_protocol-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agent_identity_protocol-0.1.0.dist-info/RECORD,,

agent_identity_protocol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aip_core/__init__.py

@@ -0,0 +1,11 @@
+from aip_core.crypto import KeyPair, verify
+from aip_core.identity import AipId
+from aip_core.document import IdentityDocument
+from aip_core.error import (
+    AipError,
+    InvalidIdentifier,
+    InvalidDocument,
+    SignatureInvalid,
+    DocumentExpired,
+    VersionUnsupported,
+)

aip_core/crypto.py

@@ -0,0 +1,68 @@
+"""Cryptographic primitives for AIP: Ed25519 key pairs, signing, and verification."""
+
+from __future__ import annotations
+
+import base58
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+from cryptography.exceptions import InvalidSignature
+
+
+class KeyPair:
+    """Ed25519 key pair for AIP identity operations."""
+
+    def __init__(self, private_key: Ed25519PrivateKey) -> None:
+        self._private_key = private_key
+
+    @classmethod
+    def generate(cls) -> KeyPair:
+        """Generate a new Ed25519 key pair."""
+        return cls(Ed25519PrivateKey.generate())
+
+    def public_key_bytes(self) -> bytes:
+        """Return the raw 32-byte public key."""
+        return self._private_key.public_key().public_bytes(
+            Encoding.Raw, PublicFormat.Raw
+        )
+
+    def private_key_bytes(self) -> bytes:
+        """Return the raw 32-byte Ed25519 private key."""
+        return self._private_key.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())
+
+    def public_key_multibase(self) -> str:
+        """Return the public key as a z-prefix base58btc multibase string."""
+        return "z" + base58.b58encode(self.public_key_bytes()).decode("ascii")
+
+    @staticmethod
+    def decode_multibase(s: str) -> bytes:
+        """Decode a z-prefix base58btc multibase string to raw bytes."""
+        if not s.startswith("z"):
+            raise ValueError("multibase string must start with 'z' (base58btc)")
+        return base58.b58decode(s[1:])
+
+    def sign(self, message: bytes) -> bytes:
+        """Sign a message with Ed25519 and return the 64-byte signature."""
+        return self._private_key.sign(message)
+
+
+def sign(kp: KeyPair, message: bytes) -> bytes:
+    """Sign a message using the given key pair."""
+    return kp.sign(message)
+
+
+def verify(public_key_bytes: bytes, message: bytes, signature: bytes) -> bool:
+    """Verify an Ed25519 signature. Returns True if valid, False otherwise."""
+    pub = Ed25519PublicKey.from_public_bytes(public_key_bytes)
+    try:
+        pub.verify(signature, message)
+        return True
+    except InvalidSignature:
+        return False

aip_core/document.py

@@ -0,0 +1,123 @@
+"""AIP Identity Document model, parsing, signing, and verification."""
+
+from __future__ import annotations
+
+import base64
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from aip_core.crypto import KeyPair, verify
+from aip_core.error import (
+    DocumentExpired,
+    InvalidDocument,
+    SignatureInvalid,
+    VersionUnsupported,
+)
+
+
+class PublicKeyEntry(BaseModel):
+    """A single public key entry in an identity document."""
+
+    id: str
+    type: str
+    public_key_multibase: str
+    valid_from: Optional[str] = None
+    valid_until: Optional[str] = None
+
+
+class IdentityDocument(BaseModel):
+    """AIP Identity Document."""
+
+    aip: str
+    id: str
+    public_keys: List[PublicKeyEntry] = Field(default_factory=list)
+    name: Optional[str] = None
+    delegation: Optional[Dict[str, Any]] = None
+    protocols: Optional[List[Dict[str, Any]]] = None
+    revocation: Optional[Dict[str, Any]] = None
+    extensions: Optional[Dict[str, Any]] = None
+    document_signature: Optional[str] = None
+    expires: Optional[str] = None
+
+    @classmethod
+    def from_json(cls, s: str) -> IdentityDocument:
+        """Parse and validate a JSON identity document string."""
+        try:
+            data = json.loads(s)
+        except json.JSONDecodeError as exc:
+            raise InvalidDocument(f"invalid JSON: {exc}") from exc
+        return cls.model_validate(data)
+
+    def canonical_json(self) -> str:
+        """Return the canonical JSON representation.
+
+        Canonical form: sorted keys, no whitespace, document_signature field excluded.
+        """
+        data = self.model_dump(exclude_none=True)
+        data.pop("document_signature", None)
+        return json.dumps(data, sort_keys=True, separators=(",", ":"))
+
+    def verify_signature(self) -> None:
+        """Verify the document signature against the first public key.
+
+        Raises SignatureInvalid if the signature is missing or does not match.
+        """
+        if not self.document_signature:
+            raise SignatureInvalid("document_signature is missing")
+        if not self.public_keys:
+            raise SignatureInvalid("no public keys in document")
+
+        # Decode the base64 signature
+        try:
+            sig_bytes = base64.b64decode(self.document_signature)
+        except Exception as exc:
+            raise SignatureInvalid(f"invalid base64 signature: {exc}") from exc
+
+        # Get the first public key
+        key_entry = self.public_keys[0]
+        pub_bytes = KeyPair.decode_multibase(key_entry.public_key_multibase)
+
+        canonical = self.canonical_json()
+        if not verify(pub_bytes, canonical.encode("utf-8"), sig_bytes):
+            raise SignatureInvalid("document signature verification failed")
+
+    def find_valid_key(self, at: datetime) -> Optional[PublicKeyEntry]:
+        """Find the first public key valid at the given datetime.
+
+        A key is valid if:
+          - valid_from is None or at >= valid_from
+          - valid_until is None or at <= valid_until
+        """
+        for key in self.public_keys:
+            if key.valid_from is not None:
+                vf = datetime.fromisoformat(key.valid_from)
+                if at < vf:
+                    continue
+            if key.valid_until is not None:
+                vu = datetime.fromisoformat(key.valid_until)
+                if at > vu:
+                    continue
+            return key
+        return None
+
+    def check_version(self) -> None:
+        """Check that the document version is supported (major version <= 1).
+
+        Raises VersionUnsupported if the major version exceeds 1.
+        """
+        try:
+            major = int(self.aip.split(".")[0])
+        except (ValueError, IndexError) as exc:
+            raise VersionUnsupported(f"cannot parse version: {self.aip!r}") from exc
+        if major > 1:
+            raise VersionUnsupported(f"unsupported AIP version: {self.aip}")
+
+    def is_expired(self, at: datetime) -> bool:
+        """Return True if the document has expired at the given datetime."""
+        if self.expires is None:
+            return False
+        exp = datetime.fromisoformat(self.expires)
+        return at >= exp

aip_core/error.py

@@ -0,0 +1,22 @@
+class AipError(Exception):
+    pass
+
+
+class InvalidIdentifier(AipError):
+    pass
+
+
+class InvalidDocument(AipError):
+    pass
+
+
+class SignatureInvalid(AipError):
+    pass
+
+
+class DocumentExpired(AipError):
+    pass
+
+
+class VersionUnsupported(AipError):
+    pass

aip_core/identity.py

@@ -0,0 +1,85 @@
+"""AIP identity parsing and resolution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from aip_core.error import InvalidIdentifier
+
+
+@dataclass(frozen=True)
+class AipId:
+    """Parsed AIP identifier.
+
+    For web identifiers:  scheme="web", domain=..., path=... (path may be None)
+    For key identifiers:  scheme="key", algorithm=..., public_key_multibase=...
+    """
+
+    scheme: str
+    domain: Optional[str] = None
+    path: Optional[str] = None
+    algorithm: Optional[str] = None
+    public_key_multibase: Optional[str] = None
+
+    @classmethod
+    def parse(cls, s: str) -> AipId:
+        """Parse an AIP identifier string.
+
+        Accepted formats:
+          - aip:web:domain/path
+          - aip:web:domain
+          - aip:key:algorithm:multibase
+
+        Raises InvalidIdentifier on malformed input.
+        """
+        if not s or not s.startswith("aip:"):
+            raise InvalidIdentifier(f"not an AIP identifier: {s!r}")
+
+        parts = s.split(":", maxsplit=2)
+        if len(parts) < 3:
+            raise InvalidIdentifier(f"too few segments: {s!r}")
+
+        _, scheme, remainder = parts
+
+        if scheme == "web":
+            # remainder might be "domain/path" or just "domain"
+            if "/" in remainder:
+                domain, path = remainder.split("/", maxsplit=1)
+                return cls(scheme="web", domain=domain, path=path)
+            else:
+                if not remainder:
+                    raise InvalidIdentifier(f"empty domain: {s!r}")
+                return cls(scheme="web", domain=remainder)
+
+        elif scheme == "key":
+            # remainder is "algorithm:multibase"
+            key_parts = remainder.split(":", maxsplit=1)
+            if len(key_parts) != 2 or not key_parts[1]:
+                raise InvalidIdentifier(
+                    f"key identifier must be aip:key:algorithm:multibase, got: {s!r}"
+                )
+            algorithm, multibase = key_parts
+            return cls(
+                scheme="key", algorithm=algorithm, public_key_multibase=multibase
+            )
+
+        else:
+            raise InvalidIdentifier(f"unknown scheme: {scheme!r}")
+
+    def resolution_url(self) -> Optional[str]:
+        """Return the HTTPS resolution URL for web identifiers, or None for key identifiers."""
+        if self.scheme != "web":
+            return None
+        if self.path:
+            return f"https://{self.domain}/.well-known/aip/{self.path}.json"
+        return f"https://{self.domain}/.well-known/aip.json"
+
+    def __str__(self) -> str:
+        if self.scheme == "web":
+            if self.path:
+                return f"aip:web:{self.domain}/{self.path}"
+            return f"aip:web:{self.domain}"
+        elif self.scheme == "key":
+            return f"aip:key:{self.algorithm}:{self.public_key_multibase}"
+        return f"aip:{self.scheme}"

aip_mcp/__init__.py

@@ -0,0 +1,2 @@
+from aip_mcp.middleware import extract_token, detect_mode, verify_request
+from aip_mcp.error import aip_error_response

aip_mcp/error.py

@@ -0,0 +1,20 @@
+def aip_error_response(code: str, message: str, status: int) -> dict:
+    return {
+        "error": {"code": code, "message": message},
+        "status": status,
+    }
+
+def token_missing():
+    return aip_error_response("aip_token_missing", "No AIP token provided", 401)
+
+def token_malformed(detail: str):
+    return aip_error_response("aip_token_malformed", detail, 401)
+
+def signature_invalid():
+    return aip_error_response("aip_signature_invalid", "Signature verification failed", 401)
+
+def token_expired():
+    return aip_error_response("aip_token_expired", "Token has expired", 401)
+
+def scope_insufficient(scope: str):
+    return aip_error_response("aip_scope_insufficient", f"Token does not authorize {scope}", 403)

aip_mcp/middleware.py

@@ -0,0 +1,54 @@
+from aip_token.compact import CompactToken
+from aip_token.error import TokenError
+
+def extract_token(headers: dict) -> str | None:
+    """Extract AIP token from headers. Case-insensitive."""
+    for key, value in headers.items():
+        if key.lower() == "x-aip-token":
+            return value
+    return None
+
+def detect_mode(token: str) -> str:
+    """Detect compact (JWT) or chained (Biscuit) mode."""
+    if token.startswith("eyJ"):
+        return "compact"
+    return "chained"
+
+def verify_request(headers: dict, public_key_bytes: bytes, required_scope: str):
+    """Verify AIP token from request headers.
+
+    For compact mode: verifies JWT and checks scope.
+    For chained mode: verifies Biscuit chain and authorizes tool.
+
+    Returns verified token on success, raises TokenError on failure.
+    """
+    from aip_mcp import error as err
+
+    token_str = extract_token(headers)
+    if not token_str:
+        raise TokenError("No AIP token provided", "aip_token_missing")
+
+    mode = detect_mode(token_str)
+
+    if mode == "compact":
+        verified = CompactToken.verify(token_str, public_key_bytes)
+        if not verified.has_scope(required_scope):
+            raise TokenError(
+                f"Token does not authorize {required_scope}",
+                "aip_scope_insufficient"
+            )
+        return verified
+    else:
+        # Chained mode - try to import, may not be available
+        try:
+            from aip_token.chained import ChainedToken
+            # public_key_bytes needs to be exactly 32 bytes for chained
+            pk = bytes(public_key_bytes)
+            chained = ChainedToken.from_base64(token_str, pk)
+            chained.authorize(required_scope, pk)
+            return chained
+        except ImportError:
+            raise TokenError(
+                "Chained mode requires biscuit-python",
+                "aip_token_malformed"
+            )

aip_token/__init__.py

@@ -0,0 +1,21 @@
+"""aip_token: JWT-based token issuance and verification for the Agent Identity Protocol."""
+
+from aip_token.claims import AipClaims
+from aip_token.compact import CompactToken
+from aip_token.delegation import DelegationBlock
+from aip_token.error import TokenError
+from aip_token.policy import SimplePolicy
+
+try:
+    from aip_token.chained import ChainedToken
+except ImportError:
+    ChainedToken = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "AipClaims",
+    "ChainedToken",
+    "CompactToken",
+    "DelegationBlock",
+    "SimplePolicy",
+    "TokenError",
+]

aip_token/chained.py

@@ -0,0 +1,206 @@
+"""ChainedToken: Biscuit-backed delegation tokens for AIP.
+
+Bridges AIP's Ed25519 key pairs with biscuit-python to provide
+cryptographically attenuated delegation chains.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from biscuit_auth import (
+    AuthorizerBuilder,
+    Biscuit,
+    BiscuitBuilder,
+    BlockBuilder,
+    Fact,
+    PrivateKey as BiscuitPrivateKey,
+    PublicKey as BiscuitPublicKey,
+    Rule,
+)
+
+from aip_core.crypto import KeyPair
+from aip_token.error import TokenError
+
+# biscuit-python >= 0.4 requires an Algorithm argument for from_bytes();
+# older versions do not.  Detect at import time.
+try:
+    from biscuit_auth import Algorithm as _Algorithm
+    _ED25519 = _Algorithm.Ed25519
+except ImportError:
+    _ED25519 = None  # type: ignore[assignment]
+
+
+def _biscuit_private_key(keypair: KeyPair) -> BiscuitPrivateKey:
+    """Convert an AIP KeyPair's private key to a biscuit PrivateKey."""
+    raw = keypair.private_key_bytes()
+    if _ED25519 is not None:
+        return BiscuitPrivateKey.from_bytes(raw, _ED25519)
+    return BiscuitPrivateKey.from_bytes(raw)  # type: ignore[call-arg]
+
+
+def _biscuit_public_key(raw_bytes: bytes) -> BiscuitPublicKey:
+    """Convert raw 32-byte public key bytes to a biscuit PublicKey."""
+    if _ED25519 is not None:
+        return BiscuitPublicKey.from_bytes(raw_bytes, _ED25519)
+    return BiscuitPublicKey.from_bytes(raw_bytes)  # type: ignore[call-arg]
+
+
+class ChainedToken:
+    """A Biscuit-based chained delegation token.
+
+    Supports creating authority tokens, delegating with attenuation,
+    serialization/deserialization, and authorization checks.
+    """
+
+    def __init__(
+        self,
+        biscuit: Biscuit,
+        issuer_str: str,
+        max_depth_val: int,
+        root_pubkey_bytes: bytes | None = None,
+        depth: int = 0,
+    ) -> None:
+        self._biscuit = biscuit
+        self._issuer = issuer_str
+        self._max_depth = max_depth_val
+        self._root_pubkey_bytes = root_pubkey_bytes
+        self._depth = depth
+
+    @staticmethod
+    def create_authority(
+        issuer: str,
+        scopes: list[str],
+        budget_cents: int | None,
+        max_depth: int,
+        ttl_seconds: int,
+        keypair: KeyPair,
+    ) -> ChainedToken:
+        """Create a new authority (root) token."""
+        biscuit_private = _biscuit_private_key(keypair)
+
+        expiry = datetime.now(tz=timezone.utc) + timedelta(seconds=ttl_seconds)
+
+        facts = f'identity("{issuer}");\n'
+        for scope in scopes:
+            facts += f'right("{scope}");\n'
+        if budget_cents is not None:
+            facts += f"budget({budget_cents});\n"
+        facts += f"max_depth({max_depth});\n"
+        facts += f'check if time($t), $t <= {expiry.strftime("%Y-%m-%dT%H:%M:%SZ")};\n'
+
+        builder = BiscuitBuilder(facts)
+        biscuit = builder.build(biscuit_private)
+
+        return ChainedToken(
+            biscuit,
+            issuer,
+            max_depth,
+            keypair.public_key_bytes(),
+            depth=0,
+        )
+
+    def delegate(
+        self,
+        delegator: str,
+        delegate: str,
+        scopes: list[str],
+        budget_cents: int | None,
+        context: str,
+    ) -> ChainedToken:
+        """Create a delegated (attenuated) token by appending a block.
+
+        Raises TokenError if context is empty or delegation depth is exceeded.
+        """
+        if not context or not context.strip():
+            raise TokenError("Context must be non-empty", "aip_token_malformed")
+
+        if self._depth >= self._max_depth:
+            raise TokenError("Delegation depth exceeded", "aip_depth_exceeded")
+
+        checks = f'delegator("{delegator}");\n'
+        checks += f'delegate("{delegate}");\n'
+        checks += f'context("{context}");\n'
+        for scope in scopes:
+            checks += f'check if right("{scope}");\n'
+        if budget_cents is not None:
+            checks += f"check if budget($b), $b <= {budget_cents};\n"
+
+        block = BlockBuilder(checks)
+        new_biscuit = self._biscuit.append(block)
+
+        return ChainedToken(
+            new_biscuit,
+            self._issuer,
+            self._max_depth,
+            self._root_pubkey_bytes,
+            depth=self._depth + 1,
+        )
+
+    def authorize(self, tool: str, root_public_key_bytes: bytes) -> None:
+        """Verify the token chain and authorize a specific tool invocation.
+
+        Re-verifies from serialized form to ensure the full chain is valid.
+        Raises on authorization failure.
+        """
+        biscuit_pubkey = _biscuit_public_key(root_public_key_bytes)
+        serialized = self._biscuit.to_base64()
+        verified = Biscuit.from_base64(serialized, biscuit_pubkey)
+
+        now = datetime.now(tz=timezone.utc)
+        auth_code = (
+            f'tool("{tool}");\n'
+            f'time({now.strftime("%Y-%m-%dT%H:%M:%SZ")});\n'
+            f"depth({self._depth});\n"
+            f'allow if right("{tool}");\n'
+        )
+        authorizer = AuthorizerBuilder(auth_code).build(verified)
+        authorizer.authorize()
+
+    def to_base64(self) -> str:
+        """Serialize the token to a URL-safe base64 string."""
+        return self._biscuit.to_base64()
+
+    @staticmethod
+    def from_base64(s: str, root_public_key_bytes: bytes) -> ChainedToken:
+        """Deserialize a token from base64 and verify against the root public key."""
+        biscuit_pubkey = _biscuit_public_key(root_public_key_bytes)
+        biscuit = Biscuit.from_base64(s, biscuit_pubkey)
+
+        # Extract issuer and max_depth by parsing the authority block source.
+        # We avoid using Authorizer here because it triggers all checks
+        # (tool, time) which have no matching facts during deserialization.
+        issuer = "unknown"
+        max_depth = 3
+        try:
+            source = biscuit.block_source(0)
+            if source:
+                for line in source.split("\n"):
+                    line = line.strip().rstrip(";")
+                    if line.startswith("identity("):
+                        # Extract string between quotes: identity("aip:web:...")
+                        start = line.index('"') + 1
+                        end = line.rindex('"')
+                        issuer = line[start:end]
+                    elif line.startswith("max_depth("):
+                        val = line[len("max_depth("):-1]
+                        max_depth = int(val)
+        except Exception:
+            pass
+
+        # Depth is block_count - 1 (authority block is block 0)
+        depth = biscuit.block_count() - 1
+
+        return ChainedToken(biscuit, issuer, max_depth, root_public_key_bytes, depth=depth)
+
+    def issuer(self) -> str:
+        """Return the token issuer identity."""
+        return self._issuer
+
+    def max_depth(self) -> int:
+        """Return the maximum delegation depth."""
+        return self._max_depth
+
+    def current_depth(self) -> int:
+        """Return the current delegation depth (0 for authority tokens)."""
+        return self._depth

aip_token/claims.py

@@ -0,0 +1,30 @@
+"""AIP token claims model."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class AipClaims(BaseModel):
+    """Claims carried inside an AIP compact token (JWT)."""
+
+    iss: str
+    """Issuer AIP identifier."""
+
+    sub: str
+    """Subject AIP identifier."""
+
+    scope: list[str]
+    """List of scope strings (e.g. 'tool:search')."""
+
+    budget_usd: float | None = None
+    """Optional budget ceiling in USD."""
+
+    max_depth: int = 0
+    """Maximum delegation depth. 0 means no further delegation allowed."""
+
+    iat: int
+    """Issued-at unix timestamp."""
+
+    exp: int
+    """Expiry unix timestamp."""

aip_token/compact.py

@@ -0,0 +1,73 @@
+"""Compact token format: JWT with EdDSA (Ed25519) signatures."""
+
+from __future__ import annotations
+
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from aip_core.crypto import KeyPair
+from aip_token.claims import AipClaims
+from aip_token.error import TokenError
+
+
+class CompactToken:
+    """AIP compact token backed by a JWT with EdDSA signatures."""
+
+    def __init__(self, claims: AipClaims) -> None:
+        self._claims = claims
+
+    @property
+    def claims(self) -> AipClaims:
+        """Return the verified claims."""
+        return self._claims
+
+    def has_scope(self, scope: str) -> bool:
+        """Return True if *scope* is present in the token's scope list."""
+        return scope in self._claims.scope
+
+    # -- static / class methods -------------------------------------------
+
+    @staticmethod
+    def create(claims: AipClaims, keypair: KeyPair) -> str:
+        """Create a signed compact token (JWT) from *claims* using *keypair*.
+
+        The resulting JWT carries header ``{"alg": "EdDSA", "typ": "aip+jwt"}``.
+        """
+        payload = claims.model_dump(mode="json")
+        token: str = jwt.encode(
+            payload,
+            keypair._private_key,
+            algorithm="EdDSA",
+            headers={"typ": "aip+jwt"},
+        )
+        return token
+
+    @staticmethod
+    def verify(token_str: str, public_key_bytes: bytes) -> CompactToken:
+        """Verify *token_str* against the given raw public key bytes.
+
+        Returns a ``CompactToken`` with the decoded claims on success.
+        Raises ``TokenError`` on any failure (expired, bad signature, malformed).
+        """
+        try:
+            public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes)
+            payload = jwt.decode(
+                token_str,
+                public_key,
+                algorithms=["EdDSA"],
+            )
+            claims = AipClaims(**payload)
+            return CompactToken(claims)
+        except jwt.ExpiredSignatureError:
+            raise TokenError.token_expired()
+        except jwt.InvalidSignatureError:
+            raise TokenError.signature_invalid()
+        except jwt.DecodeError as exc:
+            raise TokenError.token_malformed(str(exc))
+        except Exception as exc:
+            raise TokenError.token_malformed(str(exc))
+
+    @staticmethod
+    def decode_header(token_str: str) -> dict:
+        """Decode the JWT header without verifying the signature."""
+        return jwt.get_unverified_header(token_str)

aip_token/delegation.py

@@ -0,0 +1,16 @@
+"""Delegation block metadata for AIP chained tokens."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class DelegationBlock:
+    """Metadata describing a single delegation step in a chained token."""
+
+    delegator: str
+    delegate: str
+    scopes: list[str]
+    budget_cents: int | None
+    context: str

aip_token/error.py

@@ -0,0 +1,61 @@
+"""Token error types for the AIP token package."""
+
+from __future__ import annotations
+
+
+class TokenError(Exception):
+    """Base error for AIP token operations."""
+
+    def __init__(self, message: str, code: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+    def error_code(self) -> str:
+        return self.code
+
+    # -- convenience constructors ------------------------------------------
+
+    @classmethod
+    def token_missing(cls) -> TokenError:
+        return cls("token is missing", "token_missing")
+
+    @classmethod
+    def token_malformed(cls, detail: str = "") -> TokenError:
+        msg = "token is malformed"
+        if detail:
+            msg = f"{msg}: {detail}"
+        return cls(msg, "token_malformed")
+
+    @classmethod
+    def signature_invalid(cls) -> TokenError:
+        return cls("signature is invalid", "signature_invalid")
+
+    @classmethod
+    def identity_unresolvable(cls, identity: str = "") -> TokenError:
+        msg = "identity cannot be resolved"
+        if identity:
+            msg = f"{msg}: {identity}"
+        return cls(msg, "identity_unresolvable")
+
+    @classmethod
+    def token_expired(cls) -> TokenError:
+        return cls("token has expired", "token_expired")
+
+    @classmethod
+    def scope_insufficient(cls, scope: str = "") -> TokenError:
+        msg = "insufficient scope"
+        if scope:
+            msg = f"{msg}: {scope}"
+        return cls(msg, "scope_insufficient")
+
+    @classmethod
+    def budget_exceeded(cls) -> TokenError:
+        return cls("budget ceiling exceeded", "budget_exceeded")
+
+    @classmethod
+    def depth_exceeded(cls) -> TokenError:
+        return cls("delegation depth exceeded", "depth_exceeded")
+
+    @classmethod
+    def key_revoked(cls) -> TokenError:
+        return cls("signing key has been revoked", "key_revoked")

aip_token/policy.py

@@ -0,0 +1,35 @@
+"""Simple policy profiles for Biscuit-based AIP tokens."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+
+
+@dataclass
+class SimplePolicy:
+    """A simple policy that generates Datalog checks for Biscuit tokens.
+
+    Budget is expressed in integer cents (Biscuit has no float support).
+    """
+
+    tools: list[str] = field(default_factory=list)
+    budget_cents: int | None = None
+    max_depth: int | None = None
+    ttl_seconds: int | None = None
+
+    def to_datalog(self) -> str:
+        rules: list[str] = []
+        if self.tools:
+            tool_list = ", ".join(f'"{t}"' for t in self.tools)
+            rules.append(f"check if tool($tool), [{tool_list}].contains($tool);")
+        if self.budget_cents is not None:
+            rules.append(f"check if budget($b), $b <= {self.budget_cents};")
+        if self.max_depth is not None:
+            rules.append(f"check if depth($d), $d <= {self.max_depth};")
+        if self.ttl_seconds is not None:
+            expiry = datetime.now(tz=timezone.utc) + timedelta(seconds=self.ttl_seconds)
+            rules.append(
+                f'check if time($t), $t <= {expiry.strftime("%Y-%m-%dT%H:%M:%SZ")};'
+            )
+        return "\n".join(rules)