tba-protocol-webauthn 0.4.0.dev2__py3-none-any.whl

tba_protocol_webauthn/__init__.py

@@ -0,0 +1,131 @@
+"""Versioned W3C Web Authentication relying-party protocol."""
+
+from .attestation import (
+    AttestationVerificationInput,
+    AttestationVerifierRegistry,
+    build_attestation_registry,
+)
+from .bindings import CAPABILITY_REQUIREMENTS
+from .ceremonies import (
+    AuthenticationExpectation,
+    RegistrationExpectation,
+    build_creation_options,
+    build_request_options,
+    verify_authentication_response,
+    verify_registration_response,
+)
+from .claims import CLAIM_NAMES
+from .codecs import (
+    AttestationObject,
+    AttestedCredentialData,
+    AuthenticatorData,
+    AuthenticatorDataFlags,
+    ParsedClientData,
+    decode_attestation_object,
+    decode_authenticator_data,
+    decode_credential_public_key,
+    parse_client_data,
+)
+from .compatibility import compatible_features
+from .configuration import WebAuthnConfiguration
+from .errors import (
+    AuthenticationVerificationError,
+    AttestationObjectError,
+    AuthenticatorDataError,
+    ClientDataError,
+    RegistrationVerificationError,
+    WebAuthnProtocolError,
+    WebAuthnVerificationError,
+)
+from .extensions import (
+    ExtensionRegistry,
+    validate_appid,
+    validate_cred_props,
+    validate_credential_protection,
+    validate_large_blob,
+    validate_payment,
+)
+from .features import BASE_FEATURES, LEVEL_3_FEATURES, WebAuthnFeature, features_for
+from .migrations import migration_path
+from .protocol import WebAuthnProtocol
+from .related_origins import origin_is_allowed
+from .schemas import (
+    AuthenticatorAssertionResponse,
+    AuthenticatorAttestationResponse,
+    AuthenticatorSelectionCriteria,
+    CollectedClientData,
+    PublicKeyCredential,
+    PublicKeyCredentialCreationOptions,
+    PublicKeyCredentialDescriptor,
+    PublicKeyCredentialParameters,
+    PublicKeyCredentialRequestOptions,
+    PublicKeyCredentialRpEntity,
+    PublicKeyCredentialUserEntity,
+)
+from .versions import (
+    CURRENT_VERSION,
+    WEB_AUTHN_REVISIONS,
+    WebAuthnRevision,
+    WebAuthnVersion,
+    resolve_revision,
+)
+
+__all__ = [
+    "AttestationObject",
+    "AttestationVerificationInput",
+    "AttestationVerifierRegistry",
+    "AttestedCredentialData",
+    "AuthenticationExpectation",
+    "AuthenticationVerificationError",
+    "AuthenticatorAssertionResponse",
+    "AuthenticatorAttestationResponse",
+    "AuthenticatorData",
+    "AuthenticatorDataError",
+    "AuthenticatorDataFlags",
+    "AuthenticatorSelectionCriteria",
+    "BASE_FEATURES",
+    "CAPABILITY_REQUIREMENTS",
+    "CLAIM_NAMES",
+    "CURRENT_VERSION",
+    "ClientDataError",
+    "CollectedClientData",
+    "ExtensionRegistry",
+    "LEVEL_3_FEATURES",
+    "ParsedClientData",
+    "PublicKeyCredential",
+    "PublicKeyCredentialCreationOptions",
+    "PublicKeyCredentialDescriptor",
+    "PublicKeyCredentialParameters",
+    "PublicKeyCredentialRequestOptions",
+    "PublicKeyCredentialRpEntity",
+    "PublicKeyCredentialUserEntity",
+    "RegistrationExpectation",
+    "RegistrationVerificationError",
+    "WEB_AUTHN_REVISIONS",
+    "WebAuthnConfiguration",
+    "WebAuthnFeature",
+    "WebAuthnProtocol",
+    "WebAuthnProtocolError",
+    "WebAuthnRevision",
+    "WebAuthnVerificationError",
+    "WebAuthnVersion",
+    "build_attestation_registry",
+    "build_creation_options",
+    "build_request_options",
+    "compatible_features",
+    "decode_attestation_object",
+    "decode_authenticator_data",
+    "decode_credential_public_key",
+    "features_for",
+    "migration_path",
+    "origin_is_allowed",
+    "parse_client_data",
+    "resolve_revision",
+    "validate_appid",
+    "validate_cred_props",
+    "validate_credential_protection",
+    "validate_large_blob",
+    "validate_payment",
+    "verify_authentication_response",
+    "verify_registration_response",
+]

tba_protocol_webauthn/attestation/__init__.py

@@ -0,0 +1,8 @@
+from .adapters import build_attestation_registry
+from .registry import AttestationVerificationInput, AttestationVerifierRegistry
+
+__all__ = [
+    "AttestationVerificationInput",
+    "AttestationVerifierRegistry",
+    "build_attestation_registry",
+]

tba_protocol_webauthn/attestation/adapters.py

@@ -0,0 +1,51 @@
+"""Normalize provider-specific attestation verifier call signatures."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .registry import AttestationVerifierRegistry
+
+
+def build_attestation_registry(
+    *,
+    packed: Callable[..., object] | None = None,
+    u2f: Callable[..., object] | None = None,
+    tpm: Callable[..., object] | None = None,
+) -> AttestationVerifierRegistry:
+    registry = AttestationVerifierRegistry()
+    if packed:
+        registry.register(
+            "packed",
+            lambda value: packed(
+                statement=value.statement,
+                authenticator_data=value.authenticator_data,
+                client_data_hash=value.client_data_hash,
+                credential_public_key=value.credential_public_key,
+            ),
+        )
+    if u2f:
+        registry.register(
+            "fido-u2f",
+            lambda value: u2f(
+                statement=value.statement,
+                rp_id_hash=value.rp_id_hash,
+                client_data_hash=value.client_data_hash,
+                credential_id=value.credential_id,
+                credential_public_key=value.credential_public_key,
+            ),
+        )
+    if tpm:
+        registry.register(
+            "tpm",
+            lambda value: tpm(
+                statement=value.statement,
+                authenticator_data=value.authenticator_data,
+                client_data_hash=value.client_data_hash,
+                credential_public_key=value.credential_public_key,
+            ),
+        )
+    return registry
+
+
+__all__ = ["build_attestation_registry"]

tba_protocol_webauthn/attestation/registry.py

@@ -0,0 +1,59 @@
+"""Attestation format dispatch without provider dependencies."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from tba_contracts_identity.public_key_authentication import AttestationTrustResult
+
+
+@dataclass(frozen=True, slots=True)
+class AttestationVerificationInput:
+    format: str
+    statement: Mapping[object, object]
+    authenticator_data: bytes
+    client_data_hash: bytes
+    rp_id_hash: bytes
+    credential_id: bytes
+    credential_public_key: bytes
+    aaguid: bytes
+
+
+AttestationVerifier = Callable[[AttestationVerificationInput], AttestationTrustResult]
+
+
+class AttestationVerifierRegistry:
+    def __init__(
+        self, verifiers: Mapping[str, AttestationVerifier] | None = None
+    ) -> None:
+        self._verifiers = dict(verifiers or {})
+
+    def register(self, format_identifier: str, verifier: AttestationVerifier) -> None:
+        if format_identifier in self._verifiers:
+            raise ValueError(
+                f"attestation verifier already registered: {format_identifier}"
+            )
+        self._verifiers[format_identifier] = verifier
+
+    def verify(self, value: AttestationVerificationInput) -> AttestationTrustResult:
+        try:
+            verifier = self._verifiers[value.format]
+        except KeyError as exc:
+            raise ValueError(
+                f"attestation format requires a configured provider: {value.format}"
+            ) from exc
+        result = verifier(value)
+        if not isinstance(result, AttestationTrustResult):
+            raise TypeError("attestation verifier must return AttestationTrustResult")
+        return result
+
+    def supported_formats(self) -> tuple[str, ...]:
+        return tuple(sorted(self._verifiers))
+
+
+__all__ = [
+    "AttestationVerificationInput",
+    "AttestationVerifier",
+    "AttestationVerifierRegistry",
+]

tba_protocol_webauthn/bindings.py

@@ -0,0 +1,46 @@
+"""Map WebAuthn wire ceremonies to stable semantic capability operations."""
+
+from tba_contracts_identity.capabilities import ProtocolCapabilityRequirement
+
+from .versions import CURRENT_VERSION
+
+CAPABILITY_REQUIREMENTS = (
+    ProtocolCapabilityRequirement(
+        "webauthn",
+        CURRENT_VERSION.identifier,
+        "webauthn-registration-begin",
+        "PublicKeyCredentialCreationOptions",
+        "credential.public-key.registration",
+        "begin_public_key_registration",
+        "public-key-registration-options",
+    ),
+    ProtocolCapabilityRequirement(
+        "webauthn",
+        CURRENT_VERSION.identifier,
+        "webauthn-registration-complete",
+        "AuthenticatorAttestationResponse",
+        "credential.public-key.registration",
+        "complete_public_key_registration",
+        "verified-public-key-registration",
+    ),
+    ProtocolCapabilityRequirement(
+        "webauthn",
+        CURRENT_VERSION.identifier,
+        "webauthn-authentication-begin",
+        "PublicKeyCredentialRequestOptions",
+        "credential.public-key.authentication",
+        "begin_public_key_authentication",
+        "public-key-authentication-options",
+    ),
+    ProtocolCapabilityRequirement(
+        "webauthn",
+        CURRENT_VERSION.identifier,
+        "webauthn-authentication-complete",
+        "AuthenticatorAssertionResponse",
+        "credential.public-key.authentication",
+        "complete_public_key_authentication",
+        "verified-public-key-assertion",
+    ),
+)
+
+__all__ = ["CAPABILITY_REQUIREMENTS"]

tba_protocol_webauthn/ceremonies/__init__.py

@@ -0,0 +1,21 @@
+"""WebAuthn registration and authentication ceremonies."""
+
+from .authentication import (
+    AuthenticationExpectation,
+    build_request_options,
+    verify_authentication_response,
+)
+from .registration import (
+    RegistrationExpectation,
+    build_creation_options,
+    verify_registration_response,
+)
+
+__all__ = [
+    "AuthenticationExpectation",
+    "RegistrationExpectation",
+    "build_creation_options",
+    "build_request_options",
+    "verify_authentication_response",
+    "verify_registration_response",
+]

tba_protocol_webauthn/ceremonies/authentication.py

@@ -0,0 +1,169 @@
+"""WebAuthn Level 2 authentication ceremony processing."""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+from dataclasses import dataclass
+
+from tba_contracts_identity.public_key_authentication import (
+    AuthenticatorProvenanceEvidence,
+    CredentialBackupEvidence,
+    CredentialLifecycleStatus,
+    PublicKeyAuthenticationEvidence,
+    PublicKeyCredentialSource,
+    UserPresenceEvidence,
+    UserVerificationEvidence,
+    VerifiedPublicKeyAssertion,
+    VerifierBindingEvidence,
+)
+from tba_provider_cose_cryptography import verify_detached_signature
+
+from ..codecs import decode_authenticator_data, parse_client_data
+from ..errors import AuthenticationVerificationError
+from ..schemas import (
+    PublicKeyCredential,
+    PublicKeyCredentialDescriptor,
+    PublicKeyCredentialRequestOptions,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticationExpectation:
+    ceremony_id: str
+    rp_id: str
+    origin: str
+    challenge: bytes
+    credential: PublicKeyCredentialSource
+    user_verification: str = "preferred"
+
+
+def build_request_options(
+    *,
+    rp_id: str,
+    allowed_credentials: tuple[PublicKeyCredentialSource, ...] = (),
+    user_verification: str = "preferred",
+    timeout_ms: int = 300_000,
+    challenge: bytes | None = None,
+) -> PublicKeyCredentialRequestOptions:
+    return PublicKeyCredentialRequestOptions(
+        challenge=challenge or secrets.token_bytes(32),
+        timeout=timeout_ms,
+        rp_id=rp_id,
+        allow_credentials=tuple(
+            PublicKeyCredentialDescriptor(
+                id=item.external_id, transports=item.transports
+            )
+            for item in allowed_credentials
+        ),
+        user_verification=user_verification,
+    )
+
+
+def verify_authentication_response(
+    credential: PublicKeyCredential,
+    *,
+    expected: AuthenticationExpectation,
+) -> VerifiedPublicKeyAssertion:
+    try:
+        source = expected.credential
+        if source.status is not CredentialLifecycleStatus.ACTIVE:
+            raise AuthenticationVerificationError("credential is not active")
+        if source.binding.rp_id != expected.rp_id:
+            raise AuthenticationVerificationError(
+                "credential is not bound to the relying party"
+            )
+        if credential.type != "public-key" or not secrets.compare_digest(
+            credential.raw_id, source.external_id
+        ):
+            raise AuthenticationVerificationError(
+                "asserted credential identifier does not match"
+            )
+        response = credential.response
+        if not hasattr(response, "signature"):
+            raise AuthenticationVerificationError(
+                "authentication requires an assertion response"
+            )
+        client = parse_client_data(
+            response.client_data_json,
+            expected_type="webauthn.get",
+            expected_challenge=expected.challenge,
+            expected_origin=expected.origin,
+        )
+        if client.value.cross_origin:
+            raise AuthenticationVerificationError(
+                "cross-origin authentication is not enabled"
+            )
+        auth = decode_authenticator_data(response.authenticator_data)
+        if not auth.matches_rp_id_hash(
+            hashlib.sha256(expected.rp_id.encode("utf-8")).digest()
+        ):
+            raise AuthenticationVerificationError(
+                "relying-party identifier hash does not match"
+            )
+        if not auth.user_present:
+            raise AuthenticationVerificationError(
+                "authenticator did not report user presence"
+            )
+        if expected.user_verification == "required" and not auth.user_verified:
+            raise AuthenticationVerificationError(
+                "authenticator did not report user verification"
+            )
+        if response.user_handle is not None and source.binding.user_handle is not None:
+            if not secrets.compare_digest(
+                response.user_handle, source.binding.user_handle
+            ):
+                raise AuthenticationVerificationError(
+                    "asserted user handle does not match"
+                )
+        if not verify_detached_signature(
+            public_key=source.public_key,
+            algorithm=source.algorithm,
+            message=response.authenticator_data + client.digest,
+            signature=response.signature,
+        ):
+            raise AuthenticationVerificationError("assertion signature is invalid")
+        if (
+            source.sign_count
+            and auth.sign_count
+            and auth.sign_count <= source.sign_count
+        ):
+            raise AuthenticationVerificationError(
+                "authenticator counter did not advance"
+            )
+        principal_id = source.binding.principal_id
+        if principal_id is None:
+            raise AuthenticationVerificationError(
+                "credential has no resolved principal binding"
+            )
+        evidence = PublicKeyAuthenticationEvidence(
+            credential_id=source.credential_id,
+            user_presence=UserPresenceEvidence(True),
+            user_verification=UserVerificationEvidence(auth.user_verified),
+            verifier_binding=VerifierBindingEvidence(
+                expected.rp_id, expected.origin, True
+            ),
+            backup=CredentialBackupEvidence(
+                eligible=bool(auth.flags & 0x08),
+                backed_up=bool(auth.flags & 0x10),
+            ),
+            provenance=AuthenticatorProvenanceEvidence(),
+        )
+        return VerifiedPublicKeyAssertion(
+            ceremony_id=expected.ceremony_id,
+            credential_id=source.credential_id,
+            principal_id=principal_id,
+            sign_count=auth.sign_count,
+            evidence=evidence,
+        )
+    except AuthenticationVerificationError:
+        raise
+    except Exception as exc:
+        raise AuthenticationVerificationError(str(exc)) from exc
+
+
+__all__ = [
+    "AuthenticationExpectation",
+    "build_request_options",
+    "verify_authentication_response",
+]