tba-protocol-cwt 0.4.0.dev2__tar.gz

tba_protocol_cwt-0.4.0.dev2/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: tba-protocol-cwt
+Version: 0.4.0.dev2
+Summary: Versioned RFC 8392 CWT claim-set composition.
+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-bases-claim (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-access-token-digest (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-audience (==0.4.0.dev2)
+Requires-Dist: tba-concrete-claim-authorization-context (==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-cwt (==0.4.0.dev2)
+Requires-Dist: tba-contracts-identity (==0.4.0.dev2)
+Description-Content-Type: text/markdown
+
+# tba-protocol-cwt
+
+Owns RFC 8392 version history and composition of independently packaged integer-labelled CWT claims. It does not own CBOR/COSE cryptography or key resolution.
+
+Draft `actx` and `ath` use text keys in `CWT_EXTENSION_CLAIMS`; both lookup maps
+include these extensions without treating them as registered integer labels.
+`build_cwt_claims(*claims, actx_field_labels=...)` builds a CBOR-ready
+`CwtClaimsSet`, converting `actx` fields using explicit protocol labels and
+`ath` to its 32-byte SHA-256 digest. This does not implement full DPoP verification.
+

tba_protocol_cwt-0.4.0.dev2/README.md

@@ -0,0 +1,9 @@
+# tba-protocol-cwt
+
+Owns RFC 8392 version history and composition of independently packaged integer-labelled CWT claims. It does not own CBOR/COSE cryptography or key resolution.
+
+Draft `actx` and `ath` use text keys in `CWT_EXTENSION_CLAIMS`; both lookup maps
+include these extensions without treating them as registered integer labels.
+`build_cwt_claims(*claims, actx_field_labels=...)` builds a CBOR-ready
+`CwtClaimsSet`, converting `actx` fields using explicit protocol labels and
+`ath` to its 32-byte SHA-256 digest. This does not implement full DPoP verification.

tba_protocol_cwt-0.4.0.dev2/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name="tba-protocol-cwt"
+version="0.4.0.dev2"
+description="Versioned RFC 8392 CWT claim-set composition."
+readme="README.md"
+requires-python=">=3.10,<3.15"
+dependencies=["tba-concrete-claim-authorization-context==0.4.0.dev2",
+  "tba-concrete-claim-access-token-digest==0.4.0.dev2",
+  "tba-concrete-cwt==0.4.0.dev2",
+  "tba-contracts-identity==0.4.0.dev2",
+  "tba-bases-claim==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_cwt",from="src"}]

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

@@ -0,0 +1,73 @@
+"""Versioned CBOR Web Token protocol ownership."""
+
+from tba_contracts_identity.protocol_processing import (
+    build_protocol_capability_report,
+)
+
+from .bindings import CAPABILITY_REQUIREMENTS
+from .claims import (
+    CWT_CLAIM_BY_LABEL,
+    CWT_EXTENSION_CLAIMS,
+    build_cwt_claims,
+    CWT_LABEL_BY_CLAIM,
+    CWT_REGISTERED_CLAIMS,
+    CwtClaimBinding,
+    compose_cwt_claim_set,
+    cwt_label_for,
+)
+from .compatibility import COMPATIBILITY_PATHS, CwtCompatibility, compatibility
+from .errors import CwtProtocolError, UnsupportedCwtMediaTypeError
+from .features import FEATURES_BY_VERSION, supports
+from .migrations import migrate_claims
+from .profile import CwtProfile
+from .protocol import CwtProtocol
+from .schemas import CWT_CARRIER, CwtCarrier, select_carrier
+from .versions import (
+    CURRENT_VERSION,
+    VERSION_HISTORY,
+    VERSION_PUBLISHED,
+    VERSION_STATUS,
+    CwtVersion,
+    select_version,
+)
+
+
+def capability_report() -> dict[str, object]:
+    return build_protocol_capability_report(
+        protocol="cwt",
+        revision=CURRENT_VERSION.value,
+        features=tuple(FEATURES_BY_VERSION[CURRENT_VERSION.value]),
+        evidence_links=("tests/unit/test_cwt_standalone_claim_packages.py",),
+        extra_requirements=CAPABILITY_REQUIREMENTS,
+        include_default_artifact_requirements=False,
+    )
+
+
+__all__ = [
+    "CAPABILITY_REQUIREMENTS",
+    "COMPATIBILITY_PATHS",
+    "CURRENT_VERSION",
+    "CWT_CARRIER",
+    "CWT_REGISTERED_CLAIMS",
+    "CWT_CLAIM_BY_LABEL",
+    "CWT_EXTENSION_CLAIMS",
+    "build_cwt_claims",
+    "CWT_LABEL_BY_CLAIM",
+    "CwtClaimBinding",
+    "FEATURES_BY_VERSION",
+    "VERSION_HISTORY",
+    "VERSION_PUBLISHED",
+    "VERSION_STATUS",
+    "CwtCarrier",
+    "CwtCompatibility",
+    "CwtVersion",
+    "UnsupportedCwtMediaTypeError",
+    "capability_report",
+    "compatibility",
+    "compose_cwt_claim_set",
+    "cwt_label_for",
+    "migrate_claims",
+    "select_carrier",
+    "select_version",
+    "supports",
+]

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

@@ -0,0 +1,37 @@
+"""RFC 8392 wire operations mapped to reportable capabilities."""
+
+from tba_contracts_identity.capabilities import ProtocolCapabilityRequirement
+
+from .versions import CURRENT_VERSION
+
+CAPABILITY_REQUIREMENTS = (
+    ProtocolCapabilityRequirement(
+        "cwt",
+        CURRENT_VERSION.value,
+        "cwt-cbor-decode",
+        "CBOR map",
+        "artifact.processing",
+        "decode",
+        "cwt-claims",
+    ),
+    ProtocolCapabilityRequirement(
+        "cwt",
+        CURRENT_VERSION.value,
+        "cwt-cose-validation",
+        "COSE protected CWT",
+        "artifact.processing",
+        "validate",
+        "protected-token-envelope",
+    ),
+    ProtocolCapabilityRequirement(
+        "cwt",
+        CURRENT_VERSION.value,
+        "cwt-cbor-encode",
+        "application/cwt",
+        "artifact.processing",
+        "encode",
+        "cwt",
+    ),
+)
+
+__all__ = ["CAPABILITY_REQUIREMENTS"]

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

@@ -0,0 +1,100 @@
+"""RFC 8392 integer-label mappings for canonical semantic claims."""
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from tba_concrete_cwt import CwtClaimsSet
+from tba_concrete_claim_authorization_context import AuthorizationContextClaim
+from tba_concrete_claim_access_token_digest import AccessTokenDigestClaim
+from tba_concrete_claim_audience import AudienceClaim
+from tba_bases_claim import ClaimBase
+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, CwtVersion
+
+
+ClaimClass: TypeAlias = type[ClaimBase]
+
+
+@dataclass(frozen=True, slots=True)
+class CwtClaimBinding:
+    label: str | int
+    claim_class: ClaimClass
+
+    @property
+    def semantic_name(self) -> str:
+        return str(self.claim_class.claim_name)
+
+
+CWT_REGISTERED_CLAIMS = (
+    CwtClaimBinding(1, IssuerClaim),
+    CwtClaimBinding(2, SubjectClaim),
+    CwtClaimBinding(3, AudienceClaim),
+    CwtClaimBinding(4, ExpirationClaim),
+    CwtClaimBinding(5, NotBeforeClaim),
+    CwtClaimBinding(6, IssuedAtClaim),
+    CwtClaimBinding(7, JwtIdClaim),
+)
+# Draft extensions have no assigned integer labels; never invent IANA values.
+CWT_EXTENSION_CLAIMS = (
+    CwtClaimBinding("actx", AuthorizationContextClaim),
+    CwtClaimBinding("ath", AccessTokenDigestClaim),
+)
+CWT_LABEL_BY_CLAIM = {
+    binding.claim_class: binding.label for binding in (*CWT_REGISTERED_CLAIMS, *CWT_EXTENSION_CLAIMS)
+}
+CWT_CLAIM_BY_LABEL = {
+    binding.label: binding.claim_class for binding in (*CWT_REGISTERED_CLAIMS, *CWT_EXTENSION_CLAIMS)
+}
+
+
+def compose_cwt_claim_set(
+    *claims: ClaimBase,
+    version: CwtVersion = CURRENT_VERSION,
+) -> ClaimSet:
+    return ClaimSet(tuple(claims), "cwt", version.value)
+
+
+def cwt_label_for(claim: ClaimBase | ClaimClass) -> str | int:
+    claim_class = claim if isinstance(claim, type) else type(claim)
+    try:
+        return CWT_LABEL_BY_CLAIM[claim_class]
+    except KeyError as exc:
+        raise ValueError(
+            f"claim is not registered by CWT: {claim_class.__name__}"
+        ) from exc
+
+
+def build_cwt_claims(*claims: ClaimBase, actx_field_labels=None) -> CwtClaimsSet:
+    """Map semantic objects to CWT keys and carrier-specific values."""
+    values = {}
+    for claim in claims:
+        label = cwt_label_for(claim)
+        if label in values:
+            raise ValueError(f"duplicate CWT claim: {label}")
+        if isinstance(claim, AuthorizationContextClaim):
+            value = claim.to_cwt_value(field_labels=actx_field_labels)
+        elif isinstance(claim, AccessTokenDigestClaim):
+            value = claim.to_cwt_value()
+        else:
+            value = claim.value
+        values[label] = value
+    return CwtClaimsSet(values)
+
+
+__all__ = [
+    "CWT_CLAIM_BY_LABEL",
+    "CWT_EXTENSION_CLAIMS",
+    "build_cwt_claims",
+    "CWT_LABEL_BY_CLAIM",
+    "CWT_REGISTERED_CLAIMS",
+    "CwtClaimBinding",
+    "compose_cwt_claim_set",
+    "cwt_label_for",
+]

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

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

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

@@ -0,0 +1,12 @@
+"""CWT protocol mapping errors."""
+
+
+class CwtProtocolError(ValueError):
+    """Base error for an RFC 8392 mapping failure."""
+
+
+class UnsupportedCwtMediaTypeError(CwtProtocolError):
+    """Raised when the selected carrier is not `application/cwt`."""
+
+
+__all__ = ["CwtProtocolError", "UnsupportedCwtMediaTypeError"]

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

@@ -0,0 +1,19 @@
+"""RFC 8392 feature ownership."""
+
+from .versions import CURRENT_VERSION
+
+FEATURES_BY_VERSION = {
+    CURRENT_VERSION.value: frozenset(
+        {"registered-claims", "cbor-map", "cose-protection", "application-cwt"}
+    )
+}
+
+
+def supports(feature: str, version: str = CURRENT_VERSION.value) -> bool:
+    try:
+        return feature in FEATURES_BY_VERSION[version]
+    except KeyError as exc:
+        raise ValueError(f"unsupported CWT version: {version}") from exc
+
+
+__all__ = ["FEATURES_BY_VERSION", "supports"]

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

@@ -0,0 +1,19 @@
+"""CWT claim-map migration entry point."""
+
+from typing import Any, Mapping
+
+from .versions import CURRENT_VERSION
+
+
+def migrate_claims(
+    value: Mapping[str | int, Any],
+    *,
+    source: str,
+    target: str = CURRENT_VERSION.value,
+) -> dict[str | int, Any]:
+    if source != CURRENT_VERSION.value or target != CURRENT_VERSION.value:
+        raise ValueError(f"unsupported CWT migration: {source} -> {target}")
+    return dict(value)
+
+
+__all__ = ["migrate_claims"]

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

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class CwtProfile:
+    name: str
+    required_claim_labels: frozenset[str | int]
+    allowed_cose_message_types: frozenset[str]
+
+    def validate(self, claims: Mapping[str | int, object], cose_message_type: str) -> None:
+        if cose_message_type not in self.allowed_cose_message_types:
+            raise ValueError(
+                f"COSE message type not allowed by {self.name}: {cose_message_type}"
+            )
+        missing = self.required_claim_labels.difference(claims)
+        if missing:
+            raise ValueError(f"missing required CWT claim labels: {sorted(missing, key=str)}")

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

@@ -0,0 +1,21 @@
+from tba_concrete_cwt import CwtClaimsSet, decode_cwt_claims
+
+
+class CwtProtocol:
+    def __init__(self, cose_protocol, profile):
+        self.cose_protocol, self.profile = cose_protocol, profile
+
+    def issue(
+        self, claims: CwtClaimsSet, *, key_reference: str, headers: dict[object, object]
+    ):
+        return self.cose_protocol.sign1(
+            claims.encode(), key_reference=key_reference, headers=headers
+        )
+
+    def verify(self, envelope):
+        result = self.cose_protocol.verify1(envelope)
+        if result.payload is None:
+            raise ValueError("verified CWT has no payload")
+        claims = decode_cwt_claims(result.payload)
+        self.profile.validate(claims.claims, "Sign1")
+        return claims, result

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,25 @@
+"""RFC 8392 carrier schema descriptors."""
+
+from dataclasses import dataclass
+
+from tba_contracts_identity.tokens import TokenEnvelopeFormat
+
+from .errors import UnsupportedCwtMediaTypeError
+
+
+@dataclass(frozen=True, slots=True)
+class CwtCarrier:
+    media_type: str
+    envelope_format: TokenEnvelopeFormat
+
+
+CWT_CARRIER = CwtCarrier("application/cwt", TokenEnvelopeFormat.CWT)
+
+
+def select_carrier(media_type: str) -> CwtCarrier:
+    if media_type != CWT_CARRIER.media_type:
+        raise UnsupportedCwtMediaTypeError(f"unsupported CWT media type: {media_type}")
+    return CWT_CARRIER
+
+
+__all__ = ["CWT_CARRIER", "CwtCarrier", "select_carrier"]

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

@@ -0,0 +1,30 @@
+"""RFC 8392 version ownership."""
+
+from enum import StrEnum
+
+
+class CwtVersion(StrEnum):
+    RFC8392 = "RFC8392"
+
+
+CURRENT_VERSION = CwtVersion.RFC8392
+VERSION_HISTORY = (CwtVersion.RFC8392,)
+VERSION_STATUS = {CwtVersion.RFC8392.value: "standards-track"}
+VERSION_PUBLISHED = {CwtVersion.RFC8392.value: "2018-05"}
+
+
+def select_version(identifier: str = CURRENT_VERSION.value) -> CwtVersion:
+    try:
+        return CwtVersion(identifier)
+    except ValueError as exc:
+        raise ValueError(f"unsupported CWT version: {identifier}") from exc
+
+
+__all__ = [
+    "CURRENT_VERSION",
+    "VERSION_HISTORY",
+    "VERSION_PUBLISHED",
+    "VERSION_STATUS",
+    "CwtVersion",
+    "select_version",
+]