tba-protocol-gnap 0.4.0.dev2__tar.gz

tba_protocol_gnap-0.4.0.dev2/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: tba-protocol-gnap
+Version: 0.4.0.dev2
+Summary: Versioned RFC 9635 Grant Negotiation and Authorization Protocol mapping.
+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-delegated-access-negotiation (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-assertions (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-subject-identifiers (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-updated-at-rfc3339 (==0.4.0.dev2)
+Requires-Dist: tba-contracts-identity (==0.4.0.dev2)

tba_protocol_gnap-0.4.0.dev2/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "tba-protocol-gnap"
+version = "0.4.0.dev2"
+description = "Versioned RFC 9635 Grant Negotiation and Authorization Protocol mapping."
+requires-python = ">=3.10,<3.15"
+license = "Apache-2.0"
+dependencies = [
+    "tba-concrete-claim-assertions==0.4.0.dev2",
+    "tba-concrete-claim-subject-identifiers==0.4.0.dev2",
+    "tba-concrete-claim-updated-at-rfc3339==0.4.0.dev2",
+    "tba-capability-delegated-access-negotiation==0.4.0.dev2",
+    "tba-contracts-identity==0.4.0.dev2",
+]
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+[tool.poetry]
+packages = [{ include = "tba_protocol_gnap", from = "src" }]

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

@@ -0,0 +1,55 @@
+"""Versioned RFC 9635 GNAP protocol ownership."""
+
+from tba_contracts_identity.protocol_processing import (
+    build_protocol_capability_report,
+)
+
+from .bindings import CAPABILITY_REQUIREMENTS
+from .claims import GNAP_SUBJECT_CLAIM_CLASSES, compose_gnap_subject_claim_set
+from .compatibility import COMPATIBILITY_PATHS, GnapCompatibility, compatibility
+from .errors import (
+    GnapOperationUnavailableError,
+    GnapProtocolError,
+    GnapSchemaError,
+)
+from .features import FEATURES_BY_VERSION, supports
+from .migrations import migrate_request
+from .protocol import GnapProtocol
+from .schemas import GnapRequest, parse_gnap_request, serialize_gnap_result
+from .versions import CURRENT_VERSION, VERSION_HISTORY, GnapVersion, select_version
+
+
+def capability_report() -> dict[str, object]:
+    return build_protocol_capability_report(
+        protocol="gnap",
+        revision=CURRENT_VERSION.identifier,
+        features=tuple(FEATURES_BY_VERSION[CURRENT_VERSION.identifier]),
+        evidence_links=("tests/unit/test_versioned_gnap_protocol.py",),
+        extra_requirements=CAPABILITY_REQUIREMENTS,
+        include_default_artifact_requirements=False,
+    )
+
+
+__all__ = [
+    "CAPABILITY_REQUIREMENTS",
+    "COMPATIBILITY_PATHS",
+    "CURRENT_VERSION",
+    "FEATURES_BY_VERSION",
+    "GNAP_SUBJECT_CLAIM_CLASSES",
+    "VERSION_HISTORY",
+    "GnapCompatibility",
+    "GnapOperationUnavailableError",
+    "GnapProtocol",
+    "GnapProtocolError",
+    "GnapRequest",
+    "GnapSchemaError",
+    "GnapVersion",
+    "capability_report",
+    "compatibility",
+    "compose_gnap_subject_claim_set",
+    "migrate_request",
+    "parse_gnap_request",
+    "select_version",
+    "serialize_gnap_result",
+    "supports",
+]

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

@@ -0,0 +1,57 @@
+"""RFC 9635 wire operations mapped to reportable capabilities."""
+
+from tba_contracts_identity.capabilities import ProtocolCapabilityRequirement
+
+from .versions import CURRENT_VERSION
+
+CAPABILITY_REQUIREMENTS = (
+    ProtocolCapabilityRequirement(
+        "gnap",
+        CURRENT_VERSION.identifier,
+        "grant-request",
+        "grant endpoint POST",
+        "grant.negotiation",
+        "request_grant",
+        "grant-negotiation-result",
+    ),
+    ProtocolCapabilityRequirement(
+        "gnap",
+        CURRENT_VERSION.identifier,
+        "grant-continuation",
+        "continuation endpoint POST/PATCH/DELETE",
+        "grant.negotiation",
+        "continue_grant",
+        "grant-negotiation-result",
+        False,
+    ),
+    ProtocolCapabilityRequirement(
+        "gnap",
+        CURRENT_VERSION.identifier,
+        "access-token-rotation",
+        "token management rotate",
+        "grant.negotiation",
+        "rotate_access_token",
+        "rotated-access-token",
+        False,
+    ),
+    ProtocolCapabilityRequirement(
+        "gnap",
+        CURRENT_VERSION.identifier,
+        "client-key-proof",
+        "GNAP request signature",
+        "artifact.processing",
+        "validate",
+        "verified-gnap-key-proof",
+    ),
+    ProtocolCapabilityRequirement(
+        "gnap",
+        CURRENT_VERSION.identifier,
+        "request-replay",
+        "GNAP request digest and proof",
+        "security.replay-protection",
+        "check_and_reserve",
+        "reserved-gnap-request",
+    ),
+)
+
+__all__ = ["CAPABILITY_REQUIREMENTS"]

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

@@ -0,0 +1,28 @@
+"""RFC 9635 subject-information claim composition."""
+
+from tba_concrete_claim_assertions import AssertionsClaim
+from tba_concrete_claim_subject_identifiers import SubjectIdentifiersClaim
+from tba_concrete_claim_updated_at_rfc3339 import UpdatedAtRfc3339Claim
+from tba_contracts_identity.claims import ClaimSet
+
+from .versions import CURRENT_VERSION
+
+GNAP_SUBJECT_CLAIM_CLASSES = (
+    SubjectIdentifiersClaim,
+    AssertionsClaim,
+    UpdatedAtRfc3339Claim,
+)
+
+
+def compose_gnap_subject_claim_set(*claims: object) -> ClaimSet:
+    unexpected = [
+        claim.name
+        for claim in claims
+        if not isinstance(claim, GNAP_SUBJECT_CLAIM_CLASSES)
+    ]
+    if unexpected:
+        raise ValueError(f"claims are not RFC 9635 subject fields: {unexpected}")
+    return ClaimSet(tuple(claims), "gnap-subject", CURRENT_VERSION.identifier)
+
+
+__all__ = ["GNAP_SUBJECT_CLAIM_CLASSES", "compose_gnap_subject_claim_set"]

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

@@ -0,0 +1,38 @@
+"""GNAP draft-to-RFC compatibility paths."""
+
+from dataclasses import dataclass
+
+from .versions import CURRENT_VERSION, VERSION_HISTORY
+
+
+@dataclass(frozen=True, slots=True)
+class GnapCompatibility:
+    source: str
+    target: str
+    compatible: bool
+    lossless: bool
+    migration_required: bool
+
+
+COMPATIBILITY_PATHS = tuple(
+    GnapCompatibility(
+        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
+) -> GnapCompatibility:
+    for path in COMPATIBILITY_PATHS:
+        if path.source == source and path.target == target:
+            return path
+    return GnapCompatibility(source, target, False, False, False)
+
+
+__all__ = ["COMPATIBILITY_PATHS", "GnapCompatibility", "compatibility"]

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

@@ -0,0 +1,20 @@
+"""RFC 9635 protocol mapping errors."""
+
+
+class GnapProtocolError(ValueError):
+    """Base error for invalid GNAP protocol material."""
+
+
+class GnapSchemaError(GnapProtocolError):
+    """Raised when a GNAP request or response has an invalid shape."""
+
+
+class GnapOperationUnavailableError(GnapProtocolError):
+    """Raised when an optional grant lifecycle operation is unavailable."""
+
+
+__all__ = [
+    "GnapOperationUnavailableError",
+    "GnapProtocolError",
+    "GnapSchemaError",
+]

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

@@ -0,0 +1,41 @@
+FEATURES_BY_VERSION = {
+    "draft-13": frozenset(
+        {"access-token-request", "client-instance", "interaction", "continuation"}
+    ),
+    "draft-ietf-gnap-core-protocol-20": frozenset(
+        {
+            "access-token-request",
+            "client-instance",
+            "interaction",
+            "continuation",
+            "subject-information",
+            "token-rotation",
+        }
+    ),
+    "RFC9635": frozenset(
+        {
+            "access-token-request",
+            "client-instance",
+            "interaction",
+            "continuation",
+            "subject-information",
+            "token-rotation",
+            "key-proofing",
+            "multiple-access-tokens",
+            "grant-modification",
+            "token-management",
+            "authorization-server-discovery",
+            "subject-identifiers-rfc9493",
+        }
+    ),
+}
+
+
+def supports(feature: str, version: str = "RFC9635") -> bool:
+    try:
+        return feature in FEATURES_BY_VERSION[version]
+    except KeyError as exc:
+        raise ValueError(f"unsupported GNAP version: {version}") from exc
+
+
+__all__ = ["FEATURES_BY_VERSION", "supports"]

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

@@ -0,0 +1,19 @@
+from typing import Any, Mapping
+
+
+def migrate_request(
+    value: Mapping[str, Any], *, source: str, target: str = "RFC9635"
+) -> dict[str, Any]:
+    if source == target:
+        return dict(value)
+    if (
+        source not in {"draft-13", "draft-ietf-gnap-core-protocol-20"}
+        or target != "RFC9635"
+    ):
+        raise ValueError(f"unsupported GNAP migration: {source} -> {target}")
+    # The supported draft request members retained their RFC 9635 wire names.
+    # Migration metadata is deliberately not injected into protocol payloads.
+    return dict(value)
+
+
+__all__ = ["migrate_request"]

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

@@ -0,0 +1,43 @@
+"""RFC 9635 mapping to the neutral grant-negotiation capability."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from tba_capability_delegated_access_negotiation import GrantNegotiationCapability
+from tba_contracts_identity.gnap import GrantContinuationRequest
+
+from .schemas import GnapRequest, parse_gnap_request, serialize_gnap_result
+
+
+class GnapProtocol:
+    version = "RFC9635"
+
+    def __init__(self, capability: GrantNegotiationCapability):
+        self._capability = capability
+
+    async def grant(self, payload: Mapping[str, Any]) -> dict[str, object]:
+        request = parse_gnap_request(payload).to_contract()
+        return serialize_gnap_result(await self._capability.request(request))
+
+    async def continue_grant(
+        self,
+        continuation_token: str,
+        *,
+        proof: str | bytes | Mapping[str, object] | None = None,
+    ) -> dict[str, object]:
+        request = GrantContinuationRequest(continuation_token, proof)
+        return serialize_gnap_result(await self._capability.continue_request(request))
+
+    async def rotate_access_token(
+        self,
+        management_token: str,
+        *,
+        proof: str | bytes | Mapping[str, object] | None = None,
+    ) -> dict[str, object]:
+        request = GrantContinuationRequest(management_token, proof)
+        return serialize_gnap_result(await self._capability.rotate(request))
+
+
+__all__ = ["GnapProtocol", "GnapRequest", "parse_gnap_request"]

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

@@ -0,0 +1,119 @@
+"""RFC 9635 request and response schema normalization."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from tba_contracts_identity.gnap import (
+    GrantAccessRequest,
+    GrantNegotiationRequest,
+    GrantNegotiationResult,
+)
+
+from .errors import GnapSchemaError
+
+
+@dataclass(frozen=True, slots=True)
+class GnapRequest:
+    access_token: tuple[Mapping[str, Any], ...]
+    client: Mapping[str, Any] | str
+    interact: Mapping[str, Any] | None = None
+    subject: Mapping[str, Any] | None = None
+
+    def to_contract(self) -> GrantNegotiationRequest:
+        requests = tuple(
+            GrantAccessRequest(
+                tuple(item["access"]),
+                label=item.get("label"),
+                flags=tuple(item.get("flags", ())),
+            )
+            for item in self.access_token
+        )
+        return GrantNegotiationRequest(
+            requests,
+            self.client,
+            dict(self.interact) if self.interact is not None else None,
+            dict(self.subject) if self.subject is not None else None,
+        )
+
+
+def _access_requests(value: object) -> tuple[Mapping[str, Any], ...]:
+    if value is None:
+        return ()
+    items = (value,) if isinstance(value, Mapping) else value
+    if not isinstance(items, Sequence) or isinstance(items, (str, bytes)):
+        raise GnapSchemaError("GNAP access_token must be an object or array")
+    requests = []
+    for item in items:
+        if not isinstance(item, Mapping):
+            raise GnapSchemaError("GNAP access_token entries must be objects")
+        access = item.get("access")
+        if (
+            not isinstance(access, Sequence)
+            or isinstance(access, (str, bytes))
+            or not access
+        ):
+            raise GnapSchemaError("GNAP access token request requires access")
+        label = item.get("label")
+        if label is not None and not isinstance(label, str):
+            raise GnapSchemaError("GNAP access token label must be a string")
+        flags = item.get("flags", ())
+        if (
+            not isinstance(flags, Sequence)
+            or isinstance(flags, (str, bytes))
+            or any(not isinstance(flag, str) for flag in flags)
+            or len(set(flags)) != len(flags)
+        ):
+            raise GnapSchemaError("GNAP access token flags must be unique strings")
+        requests.append(dict(item))
+    labels = [item.get("label") for item in requests if item.get("label") is not None]
+    if len(requests) > 1 and len(labels) != len(requests):
+        raise GnapSchemaError("multiple GNAP access token requests require labels")
+    if len(set(labels)) != len(labels):
+        raise GnapSchemaError("GNAP access token labels must be unique")
+    return tuple(requests)
+
+
+def parse_gnap_request(value: Mapping[str, Any]) -> GnapRequest:
+    access = _access_requests(value.get("access_token"))
+    subject = value.get("subject")
+    if subject is not None and not isinstance(subject, Mapping):
+        raise GnapSchemaError("GNAP subject must be an object")
+    if not access and subject is None:
+        raise GnapSchemaError("GNAP request requires access_token or subject")
+    client = value.get("client")
+    if not isinstance(client, (Mapping, str)):
+        raise GnapSchemaError("GNAP request requires a client instance")
+    interact = value.get("interact")
+    if interact is not None and not isinstance(interact, Mapping):
+        raise GnapSchemaError("GNAP interact must be an object")
+    return GnapRequest(
+        access,
+        dict(client) if isinstance(client, Mapping) else client,
+        dict(interact) if isinstance(interact, Mapping) else None,
+        dict(subject) if isinstance(subject, Mapping) else None,
+    )
+
+
+def serialize_gnap_result(result: GrantNegotiationResult) -> dict[str, object]:
+    payload: dict[str, object] = {}
+    if result.continuation is not None:
+        payload["continue"] = dict(result.continuation)
+    if result.access_tokens:
+        payload["access_token"] = (
+            dict(result.access_tokens[0])
+            if len(result.access_tokens) == 1
+            else [dict(token) for token in result.access_tokens]
+        )
+    if result.interaction is not None:
+        payload["interact"] = dict(result.interaction)
+    if result.subject is not None:
+        payload["subject"] = dict(result.subject)
+    if result.metadata:
+        payload.update(result.metadata)
+    return payload
+
+
+__all__ = ["GnapRequest", "parse_gnap_request", "serialize_gnap_result"]

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

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class GnapVersion:
+    identifier: str
+    status: str
+    published: str
+
+
+VERSION_HISTORY = (
+    GnapVersion("draft-13", "superseded-draft", "2023-03-13"),
+    GnapVersion("draft-ietf-gnap-core-protocol-20", "superseded-draft", "2024-04-24"),
+    GnapVersion("RFC9635", "proposed-standard", "2024-10"),
+)
+CURRENT_VERSION = VERSION_HISTORY[-1]
+
+
+def select_version(identifier: str = "RFC9635") -> GnapVersion:
+    for version in VERSION_HISTORY:
+        if version.identifier == identifier:
+            return version
+    raise ValueError(f"unsupported GNAP version: {identifier}")
+
+
+__all__ = ["CURRENT_VERSION", "VERSION_HISTORY", "GnapVersion", "select_version"]