tba-protocol-jwt 0.4.0.dev2__tar.gz

tba_protocol_jwt-0.4.0.dev2/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: tba-protocol-jwt
+Version: 0.4.0.dev2
+Summary: 
+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-concrete-claim-audience (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-expiration (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-issued-at (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-issuer (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-jwt-id (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-not-before (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-subject (==0.4.0.dev2)
+Requires-Dist: tba-concrete-jwt (==0.4.0.dev2)
+Requires-Dist: tba-contracts-identity (==0.4.0.dev2)
+Requires-Dist: tba-contracts-protected-envelope (==0.4.0.dev2)

tba_protocol_jwt-0.4.0.dev2/pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name="tba-protocol-jwt"
+version="0.4.0.dev2"
+requires-python=">=3.10,<3.15"
+dependencies=["tba-contracts-protected-envelope==0.4.0.dev2","tba-concrete-jwt==0.4.0.dev2","tba-contracts-identity==0.4.0.dev2","tba-concrete-claim-issuer==0.4.0.dev2","tba-concrete-claim-subject==0.4.0.dev2","tba-concrete-claim-audience==0.4.0.dev2","tba-concrete-claim-expiration==0.4.0.dev2","tba-concrete-claim-not-before==0.4.0.dev2","tba-concrete-claim-issued-at==0.4.0.dev2","tba-concrete-claim-jwt-id==0.4.0.dev2"]
+[build-system]
+requires=["poetry-core>=1.0.0"]
+build-backend="poetry.core.masonry.api"
+[tool.poetry]
+packages=[{include="tba_protocol_jwt",from="src"}]

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

@@ -0,0 +1,59 @@
+"""Versioned RFC 7519 JSON Web Token ownership."""
+
+from tba_contracts_identity.protocol_processing import (
+    build_protocol_capability_report,
+)
+
+from .protocol import JwtProtocol
+
+from .bindings import CAPABILITY_REQUIREMENTS
+from .claims import JWT_CLAIM_CLASSES, JWT_VERSION, compose_jwt_claim_set
+from .compatibility import COMPATIBILITY_PATHS, JwtCompatibility, compatibility
+from .errors import (
+    JwtProfileRequiredError,
+    JwtProtocolError,
+    UnsupportedJwtMediaTypeError,
+)
+from .features import FEATURES_BY_VERSION, supports
+from .migrations import migrate_claims
+from .profile import JwtProfile
+from .schemas import JWT_CARRIER, JwtCarrier, select_carrier
+from .versions import CURRENT_VERSION, VERSION_HISTORY, JwtVersion, select_version
+
+
+def capability_report() -> dict[str, object]:
+    return build_protocol_capability_report(
+        protocol="jwt",
+        revision=CURRENT_VERSION.identifier,
+        features=tuple(FEATURES_BY_VERSION[CURRENT_VERSION.identifier]),
+        evidence_links=("tests/unit/test_versioned_jwt_protocol.py",),
+        extra_requirements=CAPABILITY_REQUIREMENTS,
+        include_default_artifact_requirements=False,
+    )
+
+
+__all__ = [
+    "JwtProtocol",
+    "CAPABILITY_REQUIREMENTS",
+    "COMPATIBILITY_PATHS",
+    "CURRENT_VERSION",
+    "FEATURES_BY_VERSION",
+    "JWT_CARRIER",
+    "JWT_CLAIM_CLASSES",
+    "JWT_VERSION",
+    "VERSION_HISTORY",
+    "JwtCarrier",
+    "JwtCompatibility",
+    "JwtProfile",
+    "JwtProfileRequiredError",
+    "JwtProtocolError",
+    "JwtVersion",
+    "UnsupportedJwtMediaTypeError",
+    "capability_report",
+    "compatibility",
+    "compose_jwt_claim_set",
+    "migrate_claims",
+    "select_carrier",
+    "select_version",
+    "supports",
+]

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

@@ -0,0 +1,37 @@
+"""RFC 7519 structural operations mapped to semantic capabilities."""
+
+from tba_contracts_identity.capabilities import ProtocolCapabilityRequirement
+
+from .versions import CURRENT_VERSION
+
+CAPABILITY_REQUIREMENTS = (
+    ProtocolCapabilityRequirement(
+        "jwt",
+        CURRENT_VERSION.identifier,
+        "jwt-compact-decode",
+        "compact JWT",
+        "artifact.processing",
+        "decode",
+        "jwt-claims",
+    ),
+    ProtocolCapabilityRequirement(
+        "jwt",
+        CURRENT_VERSION.identifier,
+        "jwt-structural-validation",
+        "registered JWT claims and JOSE structure",
+        "artifact.processing",
+        "validate",
+        "structurally-valid-jwt",
+    ),
+    ProtocolCapabilityRequirement(
+        "jwt",
+        CURRENT_VERSION.identifier,
+        "jwt-compact-encode",
+        "application/jwt",
+        "artifact.processing",
+        "encode",
+        "jwt",
+    ),
+)
+
+__all__ = ["CAPABILITY_REQUIREMENTS"]

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

@@ -0,0 +1,35 @@
+"""RFC 7519 registered-claim composition."""
+
+from tba_concrete_claim_audience import AudienceClaim
+from tba_concrete_claim_expiration import ExpirationClaim
+from tba_concrete_claim_issued_at import IssuedAtClaim
+from tba_concrete_claim_issuer import IssuerClaim
+from tba_concrete_claim_jwt_id import JwtIdClaim
+from tba_concrete_claim_not_before import NotBeforeClaim
+from tba_concrete_claim_subject import SubjectClaim
+from tba_contracts_identity.claims import ClaimSet
+
+from .versions import CURRENT_VERSION
+
+JWT_VERSION = CURRENT_VERSION.identifier
+JWT_CLAIM_CLASSES = (
+    IssuerClaim,
+    SubjectClaim,
+    AudienceClaim,
+    ExpirationClaim,
+    NotBeforeClaim,
+    IssuedAtClaim,
+    JwtIdClaim,
+)
+
+
+def compose_jwt_claim_set(*claims: object) -> ClaimSet:
+    unexpected = [
+        claim.name for claim in claims if not isinstance(claim, JWT_CLAIM_CLASSES)
+    ]
+    if unexpected:
+        raise ValueError(f"claims are not registered by {JWT_VERSION}: {unexpected}")
+    return ClaimSet(tuple(claims), "jwt", JWT_VERSION)
+
+
+__all__ = ["JWT_CLAIM_CLASSES", "JWT_VERSION", "compose_jwt_claim_set"]

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

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

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

@@ -0,0 +1,20 @@
+"""JWT protocol mapping errors."""
+
+
+class JwtProtocolError(ValueError):
+    """Base error for an RFC 7519 mapping failure."""
+
+
+class UnsupportedJwtMediaTypeError(JwtProtocolError):
+    """Raised when the selected artifact is not an application/JWT carrier."""
+
+
+class JwtProfileRequiredError(JwtProtocolError):
+    """Raised when a trust/use decision is attempted without a token profile."""
+
+
+__all__ = [
+    "JwtProfileRequiredError",
+    "JwtProtocolError",
+    "UnsupportedJwtMediaTypeError",
+]

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

@@ -0,0 +1,24 @@
+FEATURES_BY_VERSION = {
+    "draft-ietf-oauth-json-web-token-32": frozenset(
+        {"registered-claims", "public-claims", "private-claims"}
+    ),
+    "RFC7519": frozenset(
+        {
+            "registered-claims",
+            "public-claims",
+            "private-claims",
+            "nested-jwt",
+            "string-or-array-audience",
+        }
+    ),
+}
+
+
+def supports(feature: str, version: str = "RFC7519") -> bool:
+    try:
+        return feature in FEATURES_BY_VERSION[version]
+    except KeyError as exc:
+        raise ValueError(f"unsupported JWT version: {version}") from exc
+
+
+__all__ = ["FEATURES_BY_VERSION", "supports"]

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

@@ -0,0 +1,14 @@
+from typing import Any, Mapping
+
+
+def migrate_claims(
+    value: Mapping[str, Any], *, source: str, target: str = "RFC7519"
+) -> dict[str, Any]:
+    if source == target:
+        return dict(value)
+    if source != "draft-ietf-oauth-json-web-token-32" or target != "RFC7519":
+        raise ValueError(f"unsupported JWT migration: {source} -> {target}")
+    return dict(value)
+
+
+__all__ = ["migrate_claims"]

tba_protocol_jwt-0.4.0.dev2/src/tba_protocol_jwt/profile.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class JwtProfile:
+    name: str
+    allowed_types: frozenset[str]
+    required_claims: frozenset[str]
+    allowed_algorithms: frozenset[str]
+
+    def validate(
+        self, headers: Mapping[str, object], claims: Mapping[str, object]
+    ) -> None:
+        token_type = headers.get("typ")
+        if token_type not in self.allowed_types:
+            raise ValueError(f"unexpected token type for {self.name}: {token_type}")
+        algorithm = headers.get("alg")
+        if algorithm in {None, "none"} or algorithm not in self.allowed_algorithms:
+            raise ValueError(f"algorithm not allowed by {self.name}: {algorithm}")
+        missing = self.required_claims.difference(claims)
+        if missing:
+            raise ValueError(f"missing required claims: {sorted(missing)}")

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

@@ -0,0 +1,34 @@
+import json
+from tba_concrete_jwt import validate_registered_claims
+from tba_contracts_protected_envelope import (
+    EnvelopeVerificationRequest,
+    ProtectedEnvelope,
+)
+
+
+class JwtProtocol:
+    def __init__(self, capability, profile):
+        self.capability, self.profile = capability, profile
+
+    def verify(
+        self,
+        envelope: ProtectedEnvelope,
+        *,
+        issuer: str | None = None,
+        audience: str | None = None,
+        now: int | None = None,
+    ):
+        result = self.capability.verify_envelope(
+            EnvelopeVerificationRequest(
+                envelope,
+                expected_profile=self.profile.name,
+                expected_issuer=issuer,
+                expected_audience=audience,
+            )
+        )
+        if not result.valid or result.payload is None:
+            raise ValueError(result.reason or "JWT signature verification failed")
+        claims = json.loads(result.payload)
+        self.profile.validate(envelope.protected_headers, claims)
+        validate_registered_claims(claims, issuer=issuer, audience=audience, now=now)
+        return claims, result

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

@@ -0,0 +1,25 @@
+"""RFC 7519 compact JWT carrier descriptors."""
+
+from dataclasses import dataclass
+
+from tba_contracts_identity.tokens import TokenEnvelopeFormat
+
+from .errors import UnsupportedJwtMediaTypeError
+
+
+@dataclass(frozen=True, slots=True)
+class JwtCarrier:
+    media_type: str
+    envelope_format: TokenEnvelopeFormat
+
+
+JWT_CARRIER = JwtCarrier("application/jwt", TokenEnvelopeFormat.JWT)
+
+
+def select_carrier(media_type: str) -> JwtCarrier:
+    if media_type != JWT_CARRIER.media_type:
+        raise UnsupportedJwtMediaTypeError(f"unsupported JWT media type: {media_type}")
+    return JWT_CARRIER
+
+
+__all__ = ["JWT_CARRIER", "JwtCarrier", "select_carrier"]

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

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class JwtVersion:
+    identifier: str
+    status: str
+    published: str
+
+
+VERSION_HISTORY = (
+    JwtVersion("draft-ietf-oauth-json-web-token-32", "superseded-draft", "2015-02"),
+    JwtVersion("RFC7519", "standards-track", "2015-05"),
+)
+CURRENT_VERSION = VERSION_HISTORY[-1]
+
+
+def select_version(identifier: str = "RFC7519") -> JwtVersion:
+    for version in VERSION_HISTORY:
+        if version.identifier == identifier:
+            return version
+    raise ValueError(f"unsupported JWT version: {identifier}")
+
+
+__all__ = ["CURRENT_VERSION", "VERSION_HISTORY", "JwtVersion", "select_version"]