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

tba_protocol_webauthn/ceremonies/registration.py

@@ -0,0 +1,220 @@
+"""WebAuthn Level 2 registration ceremony processing."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+from dataclasses import dataclass
+
+from tba_contracts_identity.public_key_authentication import (
+    AttestationTrustResult,
+    AttestationType,
+    CredentialBinding,
+    PublicKeyCredentialSource,
+    VerifiedCredentialRegistration,
+)
+from tba_concrete_cose import decode_cose_key
+from tba_provider_cose_cryptography import verify_detached_signature
+
+from ..codecs import decode_attestation_object, parse_client_data
+from ..attestation import AttestationVerificationInput, AttestationVerifierRegistry
+from ..errors import RegistrationVerificationError
+from ..schemas import (
+    AuthenticatorSelectionCriteria,
+    PublicKeyCredential,
+    PublicKeyCredentialCreationOptions,
+    PublicKeyCredentialDescriptor,
+    PublicKeyCredentialParameters,
+    PublicKeyCredentialRpEntity,
+    PublicKeyCredentialUserEntity,
+)
+
+
+def _identifier(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).rstrip(b"=").decode("ascii")
+
+
+@dataclass(frozen=True, slots=True)
+class RegistrationExpectation:
+    ceremony_id: str
+    tenant_id: str
+    principal_id: str
+    rp_id: str
+    origin: str
+    challenge: bytes
+    user_handle: bytes
+    allowed_algorithms: tuple[int, ...] = (-7, -257)
+    user_verification: str = "preferred"
+    attestation_verifiers: AttestationVerifierRegistry | None = None
+
+
+def build_creation_options(
+    *,
+    rp_id: str,
+    rp_name: str,
+    user_handle: bytes,
+    user_name: str,
+    user_display_name: str,
+    algorithms: tuple[int, ...] = (-7, -257),
+    excluded_credential_ids: tuple[bytes, ...] = (),
+    user_verification: str = "preferred",
+    resident_key: str = "preferred",
+    attestation: str = "none",
+    timeout_ms: int = 300_000,
+    challenge: bytes | None = None,
+) -> PublicKeyCredentialCreationOptions:
+    if not algorithms:
+        raise ValueError("at least one credential algorithm is required")
+    return PublicKeyCredentialCreationOptions(
+        challenge=challenge or secrets.token_bytes(32),
+        rp=PublicKeyCredentialRpEntity(id=rp_id, name=rp_name),
+        user=PublicKeyCredentialUserEntity(
+            id=user_handle, name=user_name, display_name=user_display_name
+        ),
+        pub_key_cred_params=tuple(
+            PublicKeyCredentialParameters(alg=value) for value in algorithms
+        ),
+        timeout=timeout_ms,
+        exclude_credentials=tuple(
+            PublicKeyCredentialDescriptor(id=value) for value in excluded_credential_ids
+        ),
+        authenticator_selection=AuthenticatorSelectionCriteria(
+            resident_key=resident_key,
+            require_resident_key=resident_key == "required",
+            user_verification=user_verification,
+        ),
+        attestation=attestation,
+    )
+
+
+def verify_registration_response(
+    credential: PublicKeyCredential,
+    *,
+    expected: RegistrationExpectation,
+) -> VerifiedCredentialRegistration:
+    try:
+        if credential.type != "public-key" or credential.raw_id == b"":
+            raise RegistrationVerificationError(
+                "registration credential type or identifier is invalid"
+            )
+        response = credential.response
+        if not hasattr(response, "attestation_object"):
+            raise RegistrationVerificationError(
+                "registration requires an attestation response"
+            )
+        client = parse_client_data(
+            response.client_data_json,
+            expected_type="webauthn.create",
+            expected_challenge=expected.challenge,
+            expected_origin=expected.origin,
+        )
+        if client.value.cross_origin:
+            raise RegistrationVerificationError(
+                "cross-origin registration is not enabled"
+            )
+        attestation = decode_attestation_object(response.attestation_object)
+        auth = attestation.authenticator_data
+        if not auth.matches_rp_id_hash(
+            hashlib.sha256(expected.rp_id.encode("utf-8")).digest()
+        ):
+            raise RegistrationVerificationError(
+                "relying-party identifier hash does not match"
+            )
+        if not auth.user_present:
+            raise RegistrationVerificationError(
+                "authenticator did not report user presence"
+            )
+        if expected.user_verification == "required" and not auth.user_verified:
+            raise RegistrationVerificationError(
+                "authenticator did not report user verification"
+            )
+        data = auth.attested_credential_data
+        if data is None:
+            raise RegistrationVerificationError(
+                "registration omitted attested credential data"
+            )
+        if not secrets.compare_digest(data.credential_id, credential.raw_id):
+            raise RegistrationVerificationError(
+                "credential identifier does not match authenticator data"
+            )
+        cose_key = decode_cose_key(data.credential_public_key)
+        algorithm = cose_key.get(3)
+        if (
+            not isinstance(algorithm, int)
+            or algorithm not in expected.allowed_algorithms
+        ):
+            raise RegistrationVerificationError("credential algorithm is not allowed")
+        if attestation.format == "none":
+            if attestation.statement:
+                raise RegistrationVerificationError(
+                    "none attestation must have an empty statement"
+                )
+            trust = AttestationTrustResult(
+                False, AttestationType.NONE, reason="attestation not requested"
+            )
+        elif attestation.format == "packed" and "x5c" not in attestation.statement:
+            statement_algorithm = attestation.statement.get("alg")
+            signature = attestation.statement.get("sig")
+            if statement_algorithm != algorithm or not isinstance(signature, bytes):
+                raise RegistrationVerificationError(
+                    "packed self-attestation statement is invalid"
+                )
+            if not verify_detached_signature(
+                public_key=data.credential_public_key,
+                algorithm=algorithm,
+                message=auth.raw + client.digest,
+                signature=signature,
+            ):
+                raise RegistrationVerificationError(
+                    "packed self-attestation signature is invalid"
+                )
+            trust = AttestationTrustResult(
+                False, AttestationType.SELF, reason="self attestation"
+            )
+        else:
+            if expected.attestation_verifiers is None:
+                raise RegistrationVerificationError(
+                    f"attestation format requires a configured provider: {attestation.format}"
+                )
+            trust = expected.attestation_verifiers.verify(
+                AttestationVerificationInput(
+                    format=attestation.format,
+                    statement=attestation.statement,
+                    authenticator_data=auth.raw,
+                    client_data_hash=client.digest,
+                    rp_id_hash=auth.rp_id_hash,
+                    credential_id=data.credential_id,
+                    credential_public_key=data.credential_public_key,
+                    aaguid=data.aaguid,
+                )
+            )
+        source = PublicKeyCredentialSource(
+            credential_id=_identifier(credential.raw_id),
+            external_id=credential.raw_id,
+            public_key=data.credential_public_key,
+            algorithm=algorithm,
+            binding=CredentialBinding(
+                tenant_id=expected.tenant_id,
+                rp_id=expected.rp_id,
+                principal_id=expected.principal_id,
+                user_handle=expected.user_handle,
+            ),
+            sign_count=auth.sign_count,
+            transports=tuple(response.transports),
+            discoverable=False,
+            backup_eligible=bool(auth.flags & 0x08),
+            backup_state=bool(auth.flags & 0x10),
+        )
+        return VerifiedCredentialRegistration(expected.ceremony_id, source, trust)
+    except RegistrationVerificationError:
+        raise
+    except Exception as exc:
+        raise RegistrationVerificationError(str(exc)) from exc
+
+
+__all__ = [
+    "RegistrationExpectation",
+    "build_creation_options",
+    "verify_registration_response",
+]

tba_protocol_webauthn/claims.py

@@ -0,0 +1,5 @@
+"""WebAuthn defines ceremonies and credential data, not an identity-claims set."""
+
+CLAIM_NAMES: tuple[str, ...] = ()
+
+__all__ = ["CLAIM_NAMES"]

tba_protocol_webauthn/codecs/__init__.py

@@ -0,0 +1,23 @@
+"""Binary codecs used by WebAuthn ceremonies."""
+
+from .attestation_object import AttestationObject, decode_attestation_object
+from .authenticator_data import (
+    AttestedCredentialData,
+    AuthenticatorData,
+    AuthenticatorDataFlags,
+    decode_authenticator_data,
+)
+from .client_data import ParsedClientData, parse_client_data
+from .credential_public_key import decode_credential_public_key
+
+__all__ = [
+    "AttestationObject",
+    "AttestedCredentialData",
+    "AuthenticatorData",
+    "AuthenticatorDataFlags",
+    "ParsedClientData",
+    "decode_attestation_object",
+    "decode_authenticator_data",
+    "decode_credential_public_key",
+    "parse_client_data",
+]

tba_protocol_webauthn/codecs/attestation_object.py

@@ -0,0 +1,55 @@
+"""Decoder for WebAuthn attestation objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+import cbor2
+
+from ..errors import WebAuthnVerificationError
+from .authenticator_data import AuthenticatorData, decode_authenticator_data
+
+MAX_ATTESTATION_OBJECT_BYTES = 131_072
+
+
+@dataclass(frozen=True, slots=True)
+class AttestationObject:
+    format: str
+    authenticator_data: AuthenticatorData
+    statement: Mapping[object, object]
+
+
+def decode_attestation_object(encoded: bytes) -> AttestationObject:
+    if (
+        not isinstance(encoded, bytes)
+        or not encoded
+        or len(encoded) > MAX_ATTESTATION_OBJECT_BYTES
+    ):
+        raise WebAuthnVerificationError(
+            "attestation object is empty or exceeds the supported size"
+        )
+    try:
+        value = cbor2.loads(encoded)
+    except Exception as exc:
+        raise WebAuthnVerificationError("attestation object is not valid CBOR") from exc
+    if not isinstance(value, dict) or set(value) != {"fmt", "authData", "attStmt"}:
+        raise WebAuthnVerificationError(
+            "attestation object must contain fmt, authData, and attStmt"
+        )
+    if not isinstance(value["fmt"], str) or not isinstance(value["authData"], bytes):
+        raise WebAuthnVerificationError("attestation object fields have invalid types")
+    if not isinstance(value["attStmt"], dict):
+        raise WebAuthnVerificationError("attestation statement must be a CBOR map")
+    return AttestationObject(
+        format=value["fmt"],
+        authenticator_data=decode_authenticator_data(value["authData"]),
+        statement=value["attStmt"],
+    )
+
+
+__all__ = [
+    "MAX_ATTESTATION_OBJECT_BYTES",
+    "AttestationObject",
+    "decode_attestation_object",
+]

tba_protocol_webauthn/codecs/authenticator_data.py

@@ -0,0 +1,120 @@
+"""Strict decoder for the WebAuthn authenticator data byte sequence."""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass
+from enum import IntFlag
+from hmac import compare_digest
+
+import cbor2
+
+from ..errors import WebAuthnVerificationError
+
+MAX_AUTHENTICATOR_DATA_BYTES = 65_536
+
+
+class AuthenticatorDataFlags(IntFlag):
+    USER_PRESENT = 0x01
+    USER_VERIFIED = 0x04
+    BACKUP_ELIGIBLE = 0x08
+    BACKUP_STATE = 0x10
+    ATTESTED_CREDENTIAL_DATA = 0x40
+    EXTENSION_DATA = 0x80
+
+
+@dataclass(frozen=True, slots=True)
+class AttestedCredentialData:
+    aaguid: bytes
+    credential_id: bytes
+    credential_public_key: bytes
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticatorData:
+    raw: bytes
+    rp_id_hash: bytes
+    flags: AuthenticatorDataFlags
+    sign_count: int
+    attested_credential_data: AttestedCredentialData | None = None
+    extensions: object | None = None
+
+    @property
+    def user_present(self) -> bool:
+        return bool(self.flags & AuthenticatorDataFlags.USER_PRESENT)
+
+    @property
+    def user_verified(self) -> bool:
+        return bool(self.flags & AuthenticatorDataFlags.USER_VERIFIED)
+
+    def matches_rp_id_hash(self, expected: bytes) -> bool:
+        return len(expected) == 32 and compare_digest(self.rp_id_hash, expected)
+
+
+def _decode_one(data: bytes, offset: int) -> tuple[object, int]:
+    stream = io.BytesIO(data[offset:])
+    try:
+        value = cbor2.CBORDecoder(stream).decode()
+    except Exception as exc:
+        raise WebAuthnVerificationError(
+            "authenticator data contains invalid CBOR"
+        ) from exc
+    return value, offset + stream.tell()
+
+
+def decode_authenticator_data(raw: bytes) -> AuthenticatorData:
+    if (
+        not isinstance(raw, bytes)
+        or len(raw) < 37
+        or len(raw) > MAX_AUTHENTICATOR_DATA_BYTES
+    ):
+        raise WebAuthnVerificationError("authenticator data has an invalid size")
+    flags = AuthenticatorDataFlags(raw[32])
+    if bool(flags & AuthenticatorDataFlags.BACKUP_STATE) and not bool(
+        flags & AuthenticatorDataFlags.BACKUP_ELIGIBLE
+    ):
+        raise WebAuthnVerificationError(
+            "backup state cannot be set for an ineligible credential"
+        )
+    offset = 37
+    attested = None
+    if flags & AuthenticatorDataFlags.ATTESTED_CREDENTIAL_DATA:
+        if len(raw) < offset + 18:
+            raise WebAuthnVerificationError("attested credential data is truncated")
+        aaguid = raw[offset : offset + 16]
+        credential_id_length = int.from_bytes(raw[offset + 16 : offset + 18], "big")
+        offset += 18
+        if credential_id_length == 0 or len(raw) < offset + credential_id_length:
+            raise WebAuthnVerificationError("attested credential identifier is invalid")
+        credential_id = raw[offset : offset + credential_id_length]
+        offset += credential_id_length
+        _, key_end = _decode_one(raw, offset)
+        encoded_key = raw[offset:key_end]
+        attested = AttestedCredentialData(aaguid, credential_id, encoded_key)
+        offset = key_end
+    extensions = None
+    if flags & AuthenticatorDataFlags.EXTENSION_DATA:
+        extensions, offset = _decode_one(raw, offset)
+        if not isinstance(extensions, dict):
+            raise WebAuthnVerificationError(
+                "authenticator extensions must be a CBOR map"
+            )
+    if offset != len(raw):
+        raise WebAuthnVerificationError("authenticator data contains trailing bytes")
+    return AuthenticatorData(
+        raw=raw,
+        rp_id_hash=raw[:32],
+        flags=flags,
+        sign_count=int.from_bytes(raw[33:37], "big"),
+        attested_credential_data=attested,
+        extensions=extensions,
+    )
+
+
+__all__ = [
+    "MAX_AUTHENTICATOR_DATA_BYTES",
+    "AttestedCredentialData",
+    "AuthenticatorData",
+    "AuthenticatorDataFlags",
+    "decode_authenticator_data",
+]

tba_protocol_webauthn/codecs/client_data.py

@@ -0,0 +1,107 @@
+"""CollectedClientData parsing and ceremony binding checks."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from dataclasses import dataclass
+from hmac import compare_digest
+from urllib.parse import urlsplit
+
+from ..errors import WebAuthnVerificationError
+from ..schemas import CollectedClientData
+
+MAX_CLIENT_DATA_BYTES = 16_384
+
+
+def _b64url_decode(value: str) -> bytes:
+    if not isinstance(value, str) or not value:
+        raise WebAuthnVerificationError(
+            "client challenge must be a non-empty base64url string"
+        )
+    try:
+        return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+    except Exception as exc:
+        raise WebAuthnVerificationError(
+            "client challenge is not valid base64url"
+        ) from exc
+
+
+def _validated_origin(value: object) -> str:
+    if not isinstance(value, str):
+        raise WebAuthnVerificationError("client origin must be a string")
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme not in {"https", "http"}
+        or not parsed.hostname
+        or parsed.path not in {"", "/"}
+    ):
+        raise WebAuthnVerificationError("client origin is not a valid web origin")
+    if parsed.scheme == "http" and parsed.hostname not in {
+        "localhost",
+        "127.0.0.1",
+        "::1",
+    }:
+        raise WebAuthnVerificationError("WebAuthn requires HTTPS outside localhost")
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedClientData:
+    value: CollectedClientData
+    raw_json: bytes
+    digest: bytes
+    challenge: bytes
+
+
+def parse_client_data(
+    raw_json: bytes,
+    *,
+    expected_type: str,
+    expected_challenge: bytes,
+    expected_origin: str,
+) -> ParsedClientData:
+    if (
+        not isinstance(raw_json, bytes)
+        or not raw_json
+        or len(raw_json) > MAX_CLIENT_DATA_BYTES
+    ):
+        raise WebAuthnVerificationError(
+            "clientDataJSON is empty or exceeds the supported size"
+        )
+    try:
+        payload = json.loads(raw_json)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise WebAuthnVerificationError(
+            "clientDataJSON is not valid UTF-8 JSON"
+        ) from exc
+    if not isinstance(payload, dict):
+        raise WebAuthnVerificationError("clientDataJSON must contain an object")
+    if payload.get("type") != expected_type:
+        raise WebAuthnVerificationError("client data ceremony type does not match")
+    challenge = _b64url_decode(payload.get("challenge"))
+    if not compare_digest(challenge, expected_challenge):
+        raise WebAuthnVerificationError("client data challenge does not match")
+    origin = _validated_origin(payload.get("origin"))
+    if origin != _validated_origin(expected_origin):
+        raise WebAuthnVerificationError("client data origin is not allowed")
+    cross_origin = payload.get("crossOrigin", False)
+    if not isinstance(cross_origin, bool):
+        raise WebAuthnVerificationError("crossOrigin must be boolean")
+    top_origin = payload.get("topOrigin")
+    if top_origin is not None and not isinstance(top_origin, str):
+        raise WebAuthnVerificationError("topOrigin must be a string")
+    value = CollectedClientData(
+        type=expected_type,
+        challenge=payload["challenge"],
+        origin=origin,
+        cross_origin=cross_origin,
+        top_origin=top_origin,
+    )
+    return ParsedClientData(
+        value, raw_json, hashlib.sha256(raw_json).digest(), challenge
+    )
+
+
+__all__ = ["MAX_CLIENT_DATA_BYTES", "ParsedClientData", "parse_client_data"]

tba_protocol_webauthn/codecs/credential_public_key.py

@@ -0,0 +1,10 @@
+"""WebAuthn credential public-key codec."""
+
+from tba_concrete_cose import decode_cose_key
+
+
+def decode_credential_public_key(encoded: bytes):
+    return decode_cose_key(encoded)
+
+
+__all__ = ["decode_credential_public_key"]

tba_protocol_webauthn/compatibility.py

@@ -0,0 +1,11 @@
+from .features import features_for
+from .versions import WebAuthnVersion
+
+
+def compatible_features(
+    source: WebAuthnVersion | str, target: WebAuthnVersion | str
+) -> frozenset:
+    return features_for(source).intersection(features_for(target))
+
+
+__all__ = ["compatible_features"]

tba_protocol_webauthn/configuration.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+from .versions import WebAuthnVersion
+from .features import features_for
+
+
+@dataclass(frozen=True, slots=True)
+class WebAuthnConfiguration:
+    version: str = WebAuthnVersion.LEVEL_2
+    allowed_algorithms: tuple[int, ...] = (-7, -257)
+    user_verification: str = "preferred"
+    resident_key: str = "preferred"
+    attestation: str = "none"
+    timeout_ms: int = 300_000
+    enabled_features: frozenset[str] = frozenset()
+    related_origins: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.allowed_algorithms:
+            raise ValueError("at least one WebAuthn COSE algorithm is required")
+        if self.timeout_ms <= 0:
+            raise ValueError("WebAuthn timeout must be positive")
+        unsupported = self.enabled_features.difference(features_for(self.version))
+        if unsupported:
+            raise ValueError(
+                f"features are unavailable in {self.version}: {sorted(unsupported)}"
+            )
+
+    def feature_enabled(self, feature: str) -> bool:
+        return feature in self.enabled_features
+
+
+__all__ = ["WebAuthnConfiguration"]

tba_protocol_webauthn/errors.py

@@ -0,0 +1,29 @@
+class WebAuthnProtocolError(ValueError):
+    """Base WebAuthn parsing and verification failure."""
+
+
+class WebAuthnVerificationError(WebAuthnProtocolError):
+    """A supplied WebAuthn artifact failed a binding or verification rule."""
+
+
+class ClientDataError(WebAuthnProtocolError):
+    pass
+
+
+class AuthenticatorDataError(WebAuthnProtocolError):
+    pass
+
+
+class AttestationObjectError(WebAuthnProtocolError):
+    pass
+
+
+class RegistrationVerificationError(WebAuthnProtocolError):
+    pass
+
+
+class AuthenticationVerificationError(WebAuthnProtocolError):
+    pass
+
+
+__all__ = [name for name in globals() if name.endswith("Error")]

tba_protocol_webauthn/extensions/__init__.py

@@ -0,0 +1,17 @@
+from .registry import (
+    ExtensionRegistry,
+    validate_appid,
+    validate_cred_props,
+    validate_credential_protection,
+    validate_large_blob,
+    validate_payment,
+)
+
+__all__ = [
+    "ExtensionRegistry",
+    "validate_appid",
+    "validate_cred_props",
+    "validate_credential_protection",
+    "validate_large_blob",
+    "validate_payment",
+]