tba-protocol-authzen 0.4.0.dev2__tar.gz

tba_protocol_authzen-0.4.0.dev2/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: tba-protocol-authzen
+Version: 0.4.0.dev2
+Summary: OpenID AuthZEN Authorization API protocol package.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10,<3.15
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: tba-capability-policy-evaluation (==0.4.0.dev2)
+Requires-Dist: tba-contracts-identity (==0.4.0.dev2)

tba_protocol_authzen-0.4.0.dev2/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "tba-protocol-authzen"
+version = "0.4.0.dev2"
+description = "OpenID AuthZEN Authorization API protocol package."
+requires-python = ">=3.10,<3.15"
+license = "Apache-2.0"
+dependencies = [
+    "tba-contracts-identity==0.4.0.dev2",
+    "tba-capability-policy-evaluation==0.4.0.dev2",
+]
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "tba_protocol_authzen", from = "src" }]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/__init__.py

@@ -0,0 +1,66 @@
+"""Versioned OpenID AuthZEN Authorization API ownership."""
+
+from tba_contracts_identity.protocol_processing import (
+    build_protocol_capability_report,
+)
+
+from .bindings import CAPABILITY_REQUIREMENTS
+from .claims import AUTHZEN_CLAIM_CLASSES
+from .compatibility import (
+    COMPATIBILITY_PATHS,
+    AuthzenCompatibility,
+    compatibility,
+)
+from .errors import (
+    AuthzenOperationUnavailableError,
+    AuthzenProtocolError,
+    AuthzenSchemaError,
+)
+from .features import FEATURES_BY_VERSION, supports
+from .migrations import migrate_evaluation
+from .protocol import AuthzenProtocol
+from .schemas import (
+    AuthzenPdpMetadata,
+    parse_evaluation_request,
+    parse_search_request,
+    serialize_evaluation_result,
+    serialize_search_result,
+)
+from .versions import AuthzenVersion, CURRENT_VERSION, VERSION_HISTORY, select_version
+
+
+def capability_report() -> dict[str, object]:
+    return build_protocol_capability_report(
+        protocol="authzen",
+        revision=CURRENT_VERSION.identifier,
+        features=tuple(FEATURES_BY_VERSION[CURRENT_VERSION.identifier]),
+        evidence_links=("tests/unit/test_versioned_oid4vc_authzen_protocols.py",),
+        extra_requirements=CAPABILITY_REQUIREMENTS,
+        include_default_artifact_requirements=False,
+    )
+
+
+__all__ = [
+    "AUTHZEN_CLAIM_CLASSES",
+    "CAPABILITY_REQUIREMENTS",
+    "COMPATIBILITY_PATHS",
+    "CURRENT_VERSION",
+    "FEATURES_BY_VERSION",
+    "VERSION_HISTORY",
+    "AuthzenCompatibility",
+    "AuthzenOperationUnavailableError",
+    "AuthzenPdpMetadata",
+    "AuthzenProtocol",
+    "AuthzenProtocolError",
+    "AuthzenSchemaError",
+    "AuthzenVersion",
+    "capability_report",
+    "compatibility",
+    "migrate_evaluation",
+    "parse_evaluation_request",
+    "parse_search_request",
+    "select_version",
+    "serialize_evaluation_result",
+    "serialize_search_result",
+    "supports",
+]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/bindings.py

@@ -0,0 +1,79 @@
+"""Authorization API 1.0 operations mapped to reportable capabilities."""
+
+from tba_contracts_identity.capabilities import ProtocolCapabilityRequirement
+
+from .versions import CURRENT_VERSION
+
+CAPABILITY_REQUIREMENTS = (
+    ProtocolCapabilityRequirement(
+        "authzen",
+        CURRENT_VERSION.identifier,
+        "access-evaluation",
+        "/access/v1/evaluation",
+        "policy.evaluation",
+        "evaluate",
+        "policy-evaluation",
+    ),
+    ProtocolCapabilityRequirement(
+        "authzen",
+        CURRENT_VERSION.identifier,
+        "access-evaluations",
+        "/access/v1/evaluations",
+        "policy.evaluation",
+        "evaluate_many",
+        "policy-evaluations",
+        False,
+    ),
+    ProtocolCapabilityRequirement(
+        "authzen",
+        CURRENT_VERSION.identifier,
+        "search-subject",
+        "/access/v1/search/subject",
+        "policy.evaluation",
+        "search_entities",
+        "policy-subjects",
+        False,
+    ),
+    ProtocolCapabilityRequirement(
+        "authzen",
+        CURRENT_VERSION.identifier,
+        "search-resource",
+        "/access/v1/search/resource",
+        "policy.evaluation",
+        "search_entities",
+        "policy-resources",
+        False,
+    ),
+    ProtocolCapabilityRequirement(
+        "authzen",
+        CURRENT_VERSION.identifier,
+        "search-action",
+        "/access/v1/search/action",
+        "policy.evaluation",
+        "search_entities",
+        "policy-actions",
+        False,
+    ),
+    ProtocolCapabilityRequirement(
+        "authzen",
+        CURRENT_VERSION.identifier,
+        "pdp-configuration",
+        "/.well-known/authzen-configuration",
+        "policy.evaluation",
+        "describe",
+        "policy-service-description",
+        False,
+    ),
+    ProtocolCapabilityRequirement(
+        "authzen",
+        CURRENT_VERSION.identifier,
+        "signed-metadata",
+        "signed_metadata",
+        "artifact.processing",
+        "validate",
+        "verified-authzen-metadata",
+        False,
+    ),
+)
+
+__all__ = ["CAPABILITY_REQUIREMENTS"]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/claims.py

@@ -0,0 +1,10 @@
+"""AuthZEN claim-set ownership declaration.
+
+Authorization API 1.0 exchanges policy entities and decisions, not a JWT-style
+registered claim set. Signed PDP metadata is a JWT carrier whose generic claims
+remain owned by the JWT protocol package.
+"""
+
+AUTHZEN_CLAIM_CLASSES: tuple[type[object], ...] = ()
+
+__all__ = ["AUTHZEN_CLAIM_CLASSES"]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/compatibility.py

@@ -0,0 +1,38 @@
+"""Authorization API revision compatibility paths."""
+
+from dataclasses import dataclass
+
+from .versions import CURRENT_VERSION, VERSION_HISTORY
+
+
+@dataclass(frozen=True, slots=True)
+class AuthzenCompatibility:
+    source: str
+    target: str
+    compatible: bool
+    lossless: bool
+    migration_required: bool
+
+
+COMPATIBILITY_PATHS = tuple(
+    AuthzenCompatibility(
+        version.identifier,
+        CURRENT_VERSION.identifier,
+        True,
+        True,
+        version.identifier != CURRENT_VERSION.identifier,
+    )
+    for version in VERSION_HISTORY
+)
+
+
+def compatibility(
+    source: str, target: str = CURRENT_VERSION.identifier
+) -> AuthzenCompatibility:
+    for path in COMPATIBILITY_PATHS:
+        if path.source == source and path.target == target:
+            return path
+    return AuthzenCompatibility(source, target, False, False, False)
+
+
+__all__ = ["COMPATIBILITY_PATHS", "AuthzenCompatibility", "compatibility"]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/errors.py

@@ -0,0 +1,20 @@
+"""Authorization API 1.0 mapping errors."""
+
+
+class AuthzenProtocolError(ValueError):
+    """Base error for invalid AuthZEN protocol material."""
+
+
+class AuthzenSchemaError(AuthzenProtocolError):
+    """Raised when an AuthZEN entity or message has the wrong shape."""
+
+
+class AuthzenOperationUnavailableError(AuthzenProtocolError):
+    """Raised when an optional PDP operation is not configured."""
+
+
+__all__ = [
+    "AuthzenOperationUnavailableError",
+    "AuthzenProtocolError",
+    "AuthzenSchemaError",
+]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/features.py

@@ -0,0 +1,25 @@
+_EVALUATION = frozenset({"access-evaluation"})
+_BATCH = _EVALUATION | {"access-evaluations"}
+_SEARCH = _BATCH | {"search-subject", "search-resource", "search-action"}
+_DISCOVERY = _SEARCH | {"configuration", "capabilities", "signed-metadata"}
+
+FEATURES_BY_VERSION = {
+    "draft-00": _EVALUATION,
+    "draft-01": _EVALUATION,
+    "implementers-draft-1": _EVALUATION,
+    "draft-02": _BATCH,
+    "draft-03": _SEARCH,
+    "draft-04": _DISCOVERY,
+    "draft-05": _DISCOVERY,
+    "1.0": _DISCOVERY,
+}
+
+
+def supports(feature: str, version: str = "1.0") -> bool:
+    try:
+        return feature in FEATURES_BY_VERSION[version]
+    except KeyError as exc:
+        raise ValueError(f"unsupported AuthZEN version: {version}") from exc
+
+
+__all__ = ["FEATURES_BY_VERSION", "supports"]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/migrations.py

@@ -0,0 +1,28 @@
+from collections.abc import Mapping
+
+
+def migrate_evaluation(
+    payload: Mapping[str, object], from_version: str, to_version: str = "1.0"
+) -> dict[str, object]:
+    result = dict(payload)
+    if from_version == to_version:
+        return result
+    if (
+        from_version
+        in {
+            "draft-00",
+            "draft-01",
+            "implementers-draft-1",
+            "draft-02",
+            "draft-03",
+            "draft-04",
+            "draft-05",
+        }
+        and to_version == "1.0"
+    ):
+        result.setdefault("context", {})
+        return result
+    raise ValueError(f"no AuthZEN migration path from {from_version} to {to_version}")
+
+
+__all__ = ["migrate_evaluation"]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/protocol.py

@@ -0,0 +1,103 @@
+"""Authorization API 1.0 mapping to neutral policy operations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol
+
+from tba_contracts_identity.policy import (
+    PolicyEntitySearchRequest,
+    PolicyEntitySearchResult,
+    PolicyEntitySearchTarget,
+    PolicyEvaluationRequest,
+    PolicyEvaluationResult,
+)
+
+from .errors import AuthzenOperationUnavailableError, AuthzenSchemaError
+from .schemas import (
+    parse_evaluation_request,
+    parse_search_request,
+    serialize_evaluation_result,
+    serialize_search_result,
+)
+
+
+class _PolicyOperations(Protocol):
+    def evaluate(self, request: PolicyEvaluationRequest) -> PolicyEvaluationResult: ...
+
+
+def _merged_evaluations(
+    payload: Mapping[str, object],
+) -> tuple[Mapping[str, object], ...]:
+    evaluations = payload.get("evaluations")
+    if evaluations is None or evaluations == []:
+        return (payload,)
+    if not isinstance(evaluations, Sequence) or isinstance(evaluations, (str, bytes)):
+        raise AuthzenSchemaError("AuthZEN evaluations must be an array")
+    defaults = {
+        name: payload[name]
+        for name in ("subject", "action", "resource", "context")
+        if name in payload
+    }
+    merged = []
+    for item in evaluations:
+        if not isinstance(item, Mapping):
+            raise AuthzenSchemaError("each AuthZEN evaluation must be an object")
+        merged.append({**defaults, **item})
+    return tuple(merged)
+
+
+class AuthzenProtocol:
+    version = "1.0"
+
+    def __init__(self, capability: _PolicyOperations):
+        self._capability = capability
+
+    def access_evaluation(self, payload: Mapping[str, object]) -> dict[str, object]:
+        return serialize_evaluation_result(
+            self._capability.evaluate(parse_evaluation_request(payload))
+        )
+
+    def access_evaluations(self, payload: Mapping[str, object]) -> dict[str, object]:
+        merged = _merged_evaluations(payload)
+        if len(merged) == 1 and not payload.get("evaluations"):
+            return self.access_evaluation(merged[0])
+
+        requests = tuple(parse_evaluation_request(item) for item in merged)
+        evaluate_many = getattr(self._capability, "evaluate_many", None)
+        results = (
+            evaluate_many(requests)
+            if callable(evaluate_many)
+            else tuple(self._capability.evaluate(request) for request in requests)
+        )
+        return {
+            "evaluations": [serialize_evaluation_result(result) for result in results]
+        }
+
+    def _search(
+        self,
+        payload: Mapping[str, object],
+        target: PolicyEntitySearchTarget,
+    ) -> dict[str, object]:
+        search = getattr(self._capability, "search_entities", None)
+        if not callable(search):
+            raise AuthzenOperationUnavailableError(
+                f"AuthZEN {target.value} search is not configured"
+            )
+        request: PolicyEntitySearchRequest = parse_search_request(payload, target)
+        result = search(request)
+        if not isinstance(result, PolicyEntitySearchResult):
+            raise TypeError("policy search must return PolicyEntitySearchResult")
+        return serialize_search_result(result)
+
+    def search_subject(self, payload: Mapping[str, object]) -> dict[str, object]:
+        return self._search(payload, PolicyEntitySearchTarget.SUBJECT)
+
+    def search_resource(self, payload: Mapping[str, object]) -> dict[str, object]:
+        return self._search(payload, PolicyEntitySearchTarget.RESOURCE)
+
+    def search_action(self, payload: Mapping[str, object]) -> dict[str, object]:
+        return self._search(payload, PolicyEntitySearchTarget.ACTION)
+
+
+__all__ = ["AuthzenProtocol"]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/py.typed

@@ -0,0 +1 @@
+

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/schemas.py

@@ -0,0 +1,191 @@
+"""Authorization API 1.0 wire-schema normalization."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from tba_contracts_identity.policy import (
+    PolicyEntity,
+    PolicyEntityChain,
+    PolicyEntitySearchRequest,
+    PolicyEntitySearchResult,
+    PolicyEntitySearchTarget,
+    PolicyEvaluationRequest,
+    PolicyEvaluationResult,
+)
+
+from .errors import AuthzenSchemaError
+
+
+@dataclass(frozen=True, slots=True)
+class AuthzenPdpMetadata:
+    policy_decision_point: str
+    access_evaluation_endpoint: str
+    access_evaluations_endpoint: str | None = None
+    search_subject_endpoint: str | None = None
+    search_resource_endpoint: str | None = None
+    search_action_endpoint: str | None = None
+    capabilities: tuple[str, ...] = ()
+    signed_metadata: str | None = None
+
+    def to_payload(self) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "policy_decision_point": self.policy_decision_point,
+            "access_evaluation_endpoint": self.access_evaluation_endpoint,
+        }
+        for name in (
+            "access_evaluations_endpoint",
+            "search_subject_endpoint",
+            "search_resource_endpoint",
+            "search_action_endpoint",
+            "signed_metadata",
+        ):
+            if (value := getattr(self, name)) is not None:
+                payload[name] = value
+        if self.capabilities:
+            payload["capabilities"] = list(self.capabilities)
+        return payload
+
+
+def _object(value: object, name: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise AuthzenSchemaError(f"AuthZEN {name} must be an object")
+    return value
+
+
+def _properties(value: Mapping[str, object], name: str) -> Mapping[str, object]:
+    properties = value.get("properties", {})
+    if not isinstance(properties, Mapping):
+        raise AuthzenSchemaError(f"AuthZEN {name} properties must be an object")
+    return dict(properties)
+
+
+def _entity(
+    value: object,
+    name: str,
+    *,
+    identifier_required: bool = True,
+) -> PolicyEntity:
+    item = _object(value, name)
+    if name == "action":
+        identifier = item.get("name")
+        if identifier_required and not isinstance(identifier, str):
+            raise AuthzenSchemaError("AuthZEN action requires name")
+        return PolicyEntity(
+            "action",
+            identifier if isinstance(identifier, str) else "",
+            _properties(item, name),
+        )
+
+    entity_type = item.get("type")
+    identifier = item.get("id")
+    if not isinstance(entity_type, str):
+        raise AuthzenSchemaError(f"AuthZEN {name} requires type")
+    if identifier_required and not isinstance(identifier, str):
+        raise AuthzenSchemaError(f"AuthZEN {name} requires id")
+    return PolicyEntity(
+        entity_type,
+        identifier if isinstance(identifier, str) else "",
+        _properties(item, name),
+    )
+
+
+def parse_evaluation_request(
+    payload: Mapping[str, object],
+) -> PolicyEvaluationRequest:
+    context = payload.get("context", {})
+    if not isinstance(context, Mapping):
+        raise AuthzenSchemaError("AuthZEN context must be an object")
+    return PolicyEvaluationRequest(
+        PolicyEntityChain((_entity(payload.get("subject"), "subject"),)),
+        PolicyEntityChain((_entity(payload.get("action"), "action"),)),
+        PolicyEntityChain((_entity(payload.get("resource"), "resource"),)),
+        dict(context),
+    )
+
+
+def parse_search_request(
+    payload: Mapping[str, object],
+    target: PolicyEntitySearchTarget,
+) -> PolicyEntitySearchRequest:
+    context = payload.get("context", {})
+    if not isinstance(context, Mapping):
+        raise AuthzenSchemaError("AuthZEN context must be an object")
+    page = payload.get("page", {})
+    if not isinstance(page, Mapping):
+        raise AuthzenSchemaError("AuthZEN page must be an object")
+    token = page.get("token")
+    if token is not None and not isinstance(token, str):
+        raise AuthzenSchemaError("AuthZEN page token must be a string")
+
+    subject = _entity(
+        payload.get("subject"),
+        "subject",
+        identifier_required=target is not PolicyEntitySearchTarget.SUBJECT,
+    )
+    resource = _entity(
+        payload.get("resource"),
+        "resource",
+        identifier_required=target is not PolicyEntitySearchTarget.RESOURCE,
+    )
+    action = (
+        None
+        if target is PolicyEntitySearchTarget.ACTION
+        else _entity(payload.get("action"), "action")
+    )
+    return PolicyEntitySearchRequest(
+        target=target,
+        subject=subject,
+        action=action,
+        resource=resource,
+        context=dict(context),
+        page_token=token,
+    )
+
+
+def serialize_evaluation_result(result: PolicyEvaluationResult) -> dict[str, object]:
+    payload: dict[str, object] = {"decision": result.decision.allowed}
+    context: dict[str, object] = {}
+    if result.decision.reason:
+        context["reason"] = result.decision.reason
+    if result.obligations:
+        context["obligations"] = list(result.obligations)
+    if result.advice:
+        context["advice"] = list(result.advice)
+    if context:
+        payload["context"] = context
+    return payload
+
+
+def serialize_search_result(result: PolicyEntitySearchResult) -> dict[str, object]:
+    entities = []
+    for entity in result.entities:
+        item: dict[str, object]
+        if entity.entity_type == "action":
+            item = {"name": entity.identifier}
+        else:
+            item = {"type": entity.entity_type, "id": entity.identifier}
+        if entity.properties:
+            item["properties"] = dict(entity.properties)
+        entities.append(item)
+    payload: dict[str, object] = {"results": entities}
+    page: dict[str, object] = {}
+    if result.next_page_token is not None:
+        page["next_token"] = result.next_page_token
+    if result.total is not None:
+        page["total"] = result.total
+    if page:
+        payload["page"] = page
+    if result.context:
+        payload["context"] = dict(result.context)
+    return payload
+
+
+__all__ = [
+    "AuthzenPdpMetadata",
+    "parse_evaluation_request",
+    "parse_search_request",
+    "serialize_evaluation_result",
+    "serialize_search_result",
+]

tba_protocol_authzen-0.4.0.dev2/src/tba_protocol_authzen/versions.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class AuthzenVersion:
+    identifier: str
+    status: str
+    published: str
+
+
+VERSION_HISTORY = (
+    AuthzenVersion("draft-00", "superseded-draft", "2024-08-14"),
+    AuthzenVersion("draft-01", "superseded-draft", "2024-09-06"),
+    AuthzenVersion(
+        "implementers-draft-1", "superseded-implementers-draft", "2024-11-15"
+    ),
+    AuthzenVersion("draft-02", "superseded-draft", "2025-01-23"),
+    AuthzenVersion("draft-03", "superseded-draft", "2025-03-18"),
+    AuthzenVersion("draft-04", "superseded-draft", "2025-10-06"),
+    AuthzenVersion("draft-05", "proposed-final-draft", "2025-11-08"),
+    AuthzenVersion("1.0", "final", "2026-01-11"),
+)
+CURRENT_VERSION = VERSION_HISTORY[-1]
+
+
+def select_version(identifier: str = "1.0") -> AuthzenVersion:
+    for version in VERSION_HISTORY:
+        if version.identifier == identifier:
+            return version
+    raise ValueError(f"unsupported AuthZEN version: {identifier}")
+
+
+__all__ = ["AuthzenVersion", "CURRENT_VERSION", "VERSION_HISTORY", "select_version"]