agentauth-receipts 0.1.0__py3-none-any.whl

agent_receipts/__init__.py

@@ -0,0 +1 @@
+"""Deprecated package name — import ``agentauth.receipts`` instead."""

agent_receipts/cli.py

@@ -0,0 +1,5 @@
+"""Deprecated CLI entry point — use ``agentauth.receipts.cli``."""
+
+from agentauth.receipts.cli import main
+
+__all__ = ["main"]

agentauth/__init__.py

@@ -0,0 +1,99 @@
+"""AgentAuth — one system for agent identity *and* verifiable execution.
+
+AgentAuth attests an agent's identity (issuing short-lived, verifiable
+JWT-SVID credentials and capability tokens) **and** proves what that agent
+actually did (policy-checked decisions bound into a tamper-evident receipt).
+
+The two layers share one developer surface:
+
+    from agentauth import AgentAuth
+
+    auth = AgentAuth(api_key="aa_...", dev_attestation=True)  # localhost demos/tests
+    agent = auth.identify(agent_type="researcher", owner="alice@acme.ai",
+                          scopes=["db:read"])      # L1/L2 — attested identity
+
+    # Production uses a platform/SPIRE-issued attestation document instead:
+    # agent = auth.identify("researcher", "alice@acme.ai",
+    #                       attestation_document=document)
+
+    receipted = agent.wrap(model, policy=policy)   # L3/L4 — every call receipted,
+    result = receipted.run({"transaction_id": "t1"})  # bound to this identity
+
+Sub-namespaces remain available for advanced use:
+
+    agentauth.identity   # the identity client/session, errors, models
+    agentauth.receipts   # the receipt runtime, policy engine, audit, verifier
+    agentauth.backend    # the hosted FastAPI identity + verifier service
+"""
+from __future__ import annotations
+
+# --- L1/L2: identity (lightweight client surface) --------------------------- #
+from agentauth.identity import (
+    AgentAuth,
+    AgentInfo,
+    AgentSession,
+    Credential,
+    ValidationResult,
+)
+from agentauth.identity.errors import (
+    AgentAuthError,
+    AgentNotFoundError,
+    AgentRevokedError,
+    BiscuitError,
+    CapabilityDeniedError,
+    InvalidAPIKeyError,
+    InvalidTokenError,
+    ProofOfPossessionError,
+    TokenExpiredError,
+    TransportError,
+    TTLOutOfRangeError,
+)
+
+# --- L3/L4: receipts (headline runtime surface) ----------------------------- #
+from agentauth.receipts import (
+    AgentCertificate,
+    AgentWrapper,
+    AuditChain,
+    AuthorityBinding,
+    DecisionOutcome,
+    DecisionResult,
+    ExecutionProof,
+    Policy,
+    RunResult,
+    build_receipt_bundle,
+    verify_receipt_bundle,
+)
+from agentauth.receipts._version import __version__
+
+__all__ = [
+    "__version__",
+    # identity
+    "AgentAuth",
+    "AgentSession",
+    "Credential",
+    "AgentInfo",
+    "ValidationResult",
+    "AgentAuthError",
+    "TransportError",
+    "InvalidAPIKeyError",
+    "InvalidTokenError",
+    "TokenExpiredError",
+    "AgentRevokedError",
+    "AgentNotFoundError",
+    "TTLOutOfRangeError",
+    "BiscuitError",
+    "ProofOfPossessionError",
+    "CapabilityDeniedError",
+    # receipts
+    "AgentWrapper",
+    "RunResult",
+    "Policy",
+    "AgentCertificate",
+    "AuthorityBinding",
+    "AuditChain",
+    "ExecutionProof",
+    "DecisionResult",
+    "DecisionOutcome",
+    "build_receipt_bundle",
+    "verify_receipt_bundle",
+]

agentauth/backend/__init__.py

@@ -0,0 +1,9 @@
+"""AgentAuth hosted service.
+
+Backend components:
+- Identity Service  (app.identity)      -- attests workloads and issues & validates
+                                           signed JWT-SVID agent credentials
+- Identity event log (app.audit)        -- append-only log of credential lifecycle events
+"""
+
+__version__ = "0.1.0"

agentauth/backend/api_keys.py

@@ -0,0 +1,70 @@
+"""API key generation and verification helpers."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+PBKDF2_ITERATIONS = 200_000
+PBKDF2_DIGEST = "sha256"
+KEY_PREFIX = "aa_"
+
+
+def generate_api_key() -> tuple[str, str, str]:
+    """Return ``(full_api_key, lookup_prefix, encoded_hash)``."""
+    lookup = secrets.token_hex(8)
+    secret = secrets.token_urlsafe(32)
+    api_key = f"{KEY_PREFIX}{lookup}.{secret}"
+    return api_key, lookup, hash_api_key(api_key)
+
+
+def api_key_lookup_prefix(api_key: str) -> str | None:
+    """Return the public lookup prefix encoded in a modern API key."""
+    if not api_key.startswith(KEY_PREFIX):
+        return None
+    body = api_key[len(KEY_PREFIX):]
+    lookup, sep, _secret = body.partition(".")
+    if not sep or not lookup:
+        return None
+    return lookup
+
+
+def hash_api_key(api_key: str) -> str:
+    """Encode an API key with PBKDF2-HMAC for at-rest storage."""
+    salt = secrets.token_bytes(16)
+    digest = hashlib.pbkdf2_hmac(
+        PBKDF2_DIGEST,
+        api_key.encode("utf-8"),
+        salt,
+        PBKDF2_ITERATIONS,
+    )
+    return (
+        f"pbkdf2_{PBKDF2_DIGEST}${PBKDF2_ITERATIONS}$"
+        f"{salt.hex()}${digest.hex()}"
+    )
+
+
+def verify_api_key(api_key: str, encoded_hash: str | None) -> bool:
+    """Constant-time verification of an API key against an encoded hash."""
+    if not encoded_hash:
+        return False
+    try:
+        method, iterations_text, salt_hex, digest_hex = encoded_hash.split("$", 3)
+    except ValueError:
+        return False
+    if method != f"pbkdf2_{PBKDF2_DIGEST}":
+        return False
+    try:
+        iterations = int(iterations_text)
+        salt = bytes.fromhex(salt_hex)
+        expected = bytes.fromhex(digest_hex)
+    except ValueError:
+        return False
+
+    actual = hashlib.pbkdf2_hmac(
+        PBKDF2_DIGEST,
+        api_key.encode("utf-8"),
+        salt,
+        iterations,
+    )
+    return hmac.compare_digest(actual, expected)

agentauth/backend/attestation.py

@@ -0,0 +1,199 @@
+"""Attestation: turning *verified evidence* into selectors.
+
+This is the prototype's stand-in for SPIRE's two attestation stages. In
+production a SPIRE Agent proves a workload's environment to the SPIRE Server in
+two steps:
+
+1. **Node attestation** — the agent proves which node/environment it runs on
+   (Kubernetes projected SA token, AWS instance identity document, GCP metadata
+   token). The server verifies this cryptographically and derives *node
+   selectors*.
+2. **Workload attestation** — the (now-trusted) agent reports the calling
+   process's attributes (service account, pod labels, container image digest,
+   process UID), from which the server derives *workload selectors*.
+
+We cannot call a live Kubernetes TokenReview or AWS IID endpoint from an
+in-process service, so the workload presents a **signed attestation document**
+(a JWT). The signature is verified against a node trust anchor an admin
+registered for the tenant (``NodeAttestor``) — that *is* the node attestation,
+and it is real cryptography: forging provenance requires the anchor's private
+key. The verified document's ``workload`` block then feeds workload selector
+derivation. The transport is simulated; the trust decision is not.
+
+A caller never hands us a selector directly. Selectors are always *derived from
+verified evidence*, which is the whole point: an agent cannot claim an identity,
+only prove one.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+import jwt
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .errors import AttestationDeniedError
+from .models import AttestationUse, Customer, NodeAttestor, utcnow
+
+SUPPORTED_ATTESTOR_TYPES = {"k8s_psat", "aws_iid", "gcp_iit"}
+
+
+# --------------------------------------------------------------------------- #
+# Node selectors -- derived from the verified `node` block, per attestor type.
+# --------------------------------------------------------------------------- #
+def _node_selectors(attestor_type: str, node: dict) -> list[str]:
+    sel: list[str] = []
+    if attestor_type == "k8s_psat":
+        if node.get("cluster"):
+            sel.append(f"k8s_psat:cluster:{node['cluster']}")
+        if node.get("agent_ns"):
+            sel.append(f"k8s_psat:agent_ns:{node['agent_ns']}")
+        if node.get("agent_sa"):
+            sel.append(f"k8s_psat:agent_sa:{node['agent_sa']}")
+    elif attestor_type == "aws_iid":
+        if node.get("account"):
+            sel.append(f"aws_iid:account:{node['account']}")
+        if node.get("region"):
+            sel.append(f"aws_iid:region:{node['region']}")
+        if node.get("instance_id"):
+            sel.append(f"aws_iid:instance-id:{node['instance_id']}")
+    elif attestor_type == "gcp_iit":
+        if node.get("project_id"):
+            sel.append(f"gcp_iit:project-id:{node['project_id']}")
+        if node.get("zone"):
+            sel.append(f"gcp_iit:zone:{node['zone']}")
+    return sel
+
+
+# --------------------------------------------------------------------------- #
+# Workload selectors -- derived from the verified `workload` block.
+# --------------------------------------------------------------------------- #
+def derive_workload_selectors(workload: dict) -> list[str]:
+    """Map workload evidence to SPIRE-style workload selectors.
+
+    These describe the *process*: which namespace/service-account it runs as,
+    its pod labels, container image digest, and UID.
+    """
+    sel: list[str] = []
+    if workload.get("k8s_ns"):
+        sel.append(f"k8s:ns:{workload['k8s_ns']}")
+    if workload.get("k8s_sa"):
+        sel.append(f"k8s:sa:{workload['k8s_sa']}")
+    for key, value in sorted((workload.get("pod_labels") or {}).items()):
+        sel.append(f"k8s:pod-label:{key}:{value}")
+    if workload.get("image_digest"):
+        sel.append(f"docker:image-digest:{workload['image_digest']}")
+    if workload.get("unix_uid") is not None:
+        sel.append(f"unix:uid:{workload['unix_uid']}")
+    return sel
+
+
+def record_attestation_use(
+    db: Session,
+    customer_id: str,
+    *,
+    jti: str,
+    expires_at: datetime,
+) -> None:
+    """Reject attestation documents that have already minted a credential."""
+    existing = db.scalar(
+        select(AttestationUse).where(
+            AttestationUse.customer_id == customer_id,
+            AttestationUse.jti == jti,
+        )
+    )
+    if existing is not None:
+        raise AttestationDeniedError(
+            "Attestation document has already been used to mint a credential.",
+            suggestion="Fetch a fresh attestation document from the node agent and call identify() again.",
+            attestation_jti=jti,
+        )
+    db.add(
+        AttestationUse(
+            customer_id=customer_id,
+            jti=jti,
+            expires_at=expires_at,
+        )
+    )
+    db.flush()
+
+
+# --------------------------------------------------------------------------- #
+# Node attestation -- verify the signed document against a trust anchor.
+# --------------------------------------------------------------------------- #
+def verify_node_attestation(
+    db: Session, customer: Customer, attestation_document: str
+) -> tuple[dict, list[str]]:
+    """Verify a signed attestation document and return ``(payload, selectors)``.
+
+    Tries the customer's registered node attestors; the first whose public key
+    verifies the document's RS256 signature wins (that proves the node). Raises
+    :class:`AttestationDeniedError` if the document is malformed, signed by an
+    unregistered key, or stale.
+    """
+    if not attestation_document or attestation_document.count(".") != 2:
+        raise AttestationDeniedError(
+            "Attestation document is missing or not a signed JWT.",
+            suggestion=(
+                "Present the signed attestation document your node agent issues "
+                "(a JWS with node + workload evidence)."
+            ),
+        )
+
+    # Read the declared type (unverified) so we only try anchors of that type.
+    try:
+        unverified = jwt.decode(attestation_document, options={"verify_signature": False})
+    except jwt.InvalidTokenError as exc:
+        raise AttestationDeniedError(
+            "Attestation document could not be parsed.",
+            suggestion="Ensure the document is a well-formed JWS.",
+        ) from exc
+
+    declared_type = unverified.get("type")
+    anchors = list(
+        db.scalars(
+            select(NodeAttestor).where(NodeAttestor.customer_id == customer.id)
+        ).all()
+    )
+    if not anchors:
+        raise AttestationDeniedError(
+            "No node attestors are registered for this tenant.",
+            suggestion=(
+                "Register a node trust anchor at POST /v1/node-attestors before "
+                "any workload can attest."
+            ),
+        )
+
+    candidates = [a for a in anchors if declared_type is None or a.type == declared_type]
+    expired = False
+    for anchor in candidates:
+        try:
+            payload = jwt.decode(
+                attestation_document,
+                anchor.public_pem,
+                algorithms=["RS256"],
+                audience=customer.id,
+                options={"require": ["jti", "exp"]},
+            )
+        except jwt.ExpiredSignatureError:
+            expired = True
+            continue
+        except jwt.InvalidTokenError:
+            continue
+        # Verified: this anchor proves the node.
+        node = payload.get("node") or {}
+        selectors = _node_selectors(anchor.type, node)
+        return payload, selectors
+
+    if expired:
+        raise AttestationDeniedError(
+            "Attestation document has expired.",
+            suggestion="Node evidence is short-lived; re-fetch it and attest again.",
+        )
+    raise AttestationDeniedError(
+        "Attestation document is not signed by any registered node attestor.",
+        suggestion=(
+            "The signing key must match a node trust anchor registered for this "
+            "tenant. A stolen workload credential cannot forge node provenance."
+        ),
+    )

agentauth/backend/audit.py

@@ -0,0 +1,137 @@
+"""Append-only identity event log (hash-chained, DB-backed).
+
+``record_event`` is the single choke point the Identity Service calls to record
+a credential lifecycle event (issuance, revocation, key rotation, attestor /
+registration changes). Each event is appended to the ``audit_events`` table as a
+tamper-evident hash chain: ``entry_hash = H(sequence, prev_hash, ts, type,
+customer_id, ...fields)`` and each row links to the previous via ``prev_hash``.
+
+This replaces the legacy flat ``audit.jsonl`` file: the trail now lives in the
+same durable, queryable SQLite store as the rest of the identity data, so it can
+be filtered by tenant and verified without parsing a side file.
+
+Call sites pass no DB session: ``record_event`` opens its own short-lived
+session so the audit write is independent of the caller's transaction (an
+append-only log should persist regardless of the surrounding request).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import time
+from datetime import datetime
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError, OperationalError
+
+from .db import SessionLocal
+from .models import AuditEvent
+
+_lock = threading.Lock()
+_CHAIN_SCHEMA = "agentauth.audit.v1"
+_APPEND_RETRIES = 5
+
+
+def _canonical_json(value: object) -> str:
+    return json.dumps(value, default=str, sort_keys=True, separators=(",", ":"))
+
+
+def _record_hash(record: dict) -> str:
+    """Hash the canonical event material (everything but the hash itself)."""
+    material = {key: value for key, value in record.items() if key != "entry_hash"}
+    return hashlib.sha256(_canonical_json(material).encode("utf-8")).hexdigest()
+
+
+def _record_from_row(row: AuditEvent) -> dict:
+    """Reconstruct the hashed event material from a stored row."""
+    return {
+        "schema": _CHAIN_SCHEMA,
+        "sequence": row.sequence,
+        "prev_hash": row.prev_hash,
+        "ts": row.ts,
+        "type": row.type,
+        "customer_id": row.customer_id,
+        **(row.payload or {}),
+    }
+
+
+def record_event(event_type: str, customer_id: str, **fields: object) -> dict:
+    """Append an identity event to the hash-chained log and return the record."""
+    for attempt in range(_APPEND_RETRIES):
+        with _lock, SessionLocal() as db:
+            try:
+                last = db.scalars(
+                    select(AuditEvent).order_by(AuditEvent.sequence.desc()).limit(1)
+                ).first()
+                prev_hash = last.entry_hash if last is not None else None
+                next_sequence = (last.sequence + 1) if last is not None else 1
+
+                ts = datetime.utcnow().isoformat() + "Z"
+                record = {
+                    "schema": _CHAIN_SCHEMA,
+                    "sequence": next_sequence,
+                    "prev_hash": prev_hash,
+                    "ts": ts,
+                    "type": event_type,
+                    "customer_id": customer_id,
+                    **fields,
+                }
+                record["entry_hash"] = _record_hash(record)
+
+                db.add(
+                    AuditEvent(
+                        sequence=next_sequence,
+                        customer_id=customer_id,
+                        type=event_type,
+                        ts=ts,
+                        payload=dict(fields),
+                        prev_hash=prev_hash,
+                        entry_hash=record["entry_hash"],
+                    )
+                )
+                db.commit()
+                return record
+            except (IntegrityError, OperationalError):
+                db.rollback()
+                if attempt == _APPEND_RETRIES - 1:
+                    raise
+        time.sleep(0.01 * (attempt + 1))
+    raise RuntimeError("failed to append audit event")
+
+
+def read_events(customer_id: str | None = None) -> list[dict]:
+    """Return audit events (oldest first), optionally filtered by tenant.
+
+    Each event includes its ``entry_hash``; this is the queryable replacement
+    for reading the old JSONL file line by line.
+    """
+    stmt = select(AuditEvent).order_by(AuditEvent.sequence)
+    if customer_id is not None:
+        stmt = stmt.where(AuditEvent.customer_id == customer_id)
+    with SessionLocal() as db:
+        rows = db.scalars(stmt).all()
+    return [{**_record_from_row(row), "entry_hash": row.entry_hash} for row in rows]
+
+
+def verify_event_log() -> list[str]:
+    """Return integrity issues for the identity event log (empty == intact)."""
+    with SessionLocal() as db:
+        rows = db.scalars(select(AuditEvent).order_by(AuditEvent.sequence)).all()
+
+    issues: list[str] = []
+    expected_prev_hash: str | None = None
+    expected_sequence = 1
+    for row in rows:
+        if row.sequence != expected_sequence:
+            issues.append(
+                f"sequence {row.sequence}: expected {expected_sequence}"
+            )
+        if row.prev_hash != expected_prev_hash:
+            issues.append(f"sequence {row.sequence}: prev_hash mismatch")
+        if _record_hash(_record_from_row(row)) != row.entry_hash:
+            issues.append(f"sequence {row.sequence}: entry_hash mismatch")
+        expected_prev_hash = row.entry_hash
+        expected_sequence += 1
+
+    return issues

agentauth/backend/biscuit_keys.py

@@ -0,0 +1,44 @@
+"""Encrypt Biscuit root private keys at rest."""
+from __future__ import annotations
+
+from .secret_encryption import (
+    encryption_enabled,
+    encrypt_secret,
+    decrypt_secret,
+    is_encrypted_value,
+)
+
+BISCUIT_CONTEXT = "biscuit_root_ed25519_v1"
+
+
+def is_encrypted_private_hex(stored: str) -> bool:
+    return is_encrypted_value(stored)
+
+
+def is_plaintext_private_hex(stored: str) -> bool:
+    if is_encrypted_private_hex(stored):
+        return False
+    try:
+        raw = bytes.fromhex(stored)
+    except ValueError:
+        return False
+    return len(raw) == 32
+
+
+def encrypt_private_hex(plaintext_hex: str) -> str:
+    return encrypt_secret(plaintext_hex, context=BISCUIT_CONTEXT)
+
+
+def decrypt_private_hex(stored: str) -> str:
+    if is_plaintext_private_hex(stored):
+        return stored
+    return decrypt_secret(stored, context=BISCUIT_CONTEXT)
+
+
+def maybe_reencrypt_biscuit_root_key(db, root_key) -> None:
+    if not encryption_enabled() or is_encrypted_private_hex(root_key.private_hex):
+        return
+    root_key.private_hex = encrypt_private_hex(root_key.private_hex)
+    db.add(root_key)
+    db.commit()
+    db.refresh(root_key)