dnsid 0.26.0__py3-none-any.whl

dnsid/__init__.py

@@ -0,0 +1,387 @@
+"""DNSid Python SDK.
+
+Implements the DNSid Protocol for identity management and verification.
+
+Protocol layer (spec-defined):
+    IdentityManager            — primary entry point; all protocol operations flow through it
+    IdentityManagerDependencies — optional dependency bundle for IdentityManager
+    DnsidConfig                — core configuration: identity, verification, transport
+    IdentityConfig             — local identity publication settings
+    VerificationConfig         — verification policy and counterparty acceptance
+    TrustedEntity              — one counterparty allowlist entry (gi + optional key pins)
+    TransportConfig            — optional deployment/runtime DNS and TLS controls
+    RegistryConfig             — optional registry control-plane configuration
+    DnsIdTxtRecord             — _dnsid TXT record parsing, validation, serialization
+    JWKS / JWK                 — key set wrapper and individual key type
+    check_ek_ku_distinctness  — RFC 7638 thumbprint distinctness check (ek vs ku key sets)
+    AgentStatus                — status endpoint response
+    VerifiedDomain             — result of a successful verify_domain call
+    DomainLog                  — verified event history for a domain
+    DomainSnapshot             — materialized domain state at a point in time
+    LogRegistry                — factory registry for log method implementations
+    RegistryClient             — operator-side registry workflows
+
+Application profiles (not part of the DNSid protocol):
+    JoseProfile / JoseConfig   — JWT and JWS helpers (dnsid.jose)
+    HttpSignatureProfile / HttpMessageSignatureConfig
+                               — RFC 9421 HTTP Message Signatures (dnsid.http_signatures)
+    OIDCProfile / OIDCConfig   — OIDC token minting and verification (dnsid.oidc)
+
+Key management:
+    LocalKeyProvider           — file-backed EdDSA/ES256 KeyProvider with key rotation lifecycle
+    AwsKmsKeyProvider          — AWS KMS-backed KeyProvider (optional dep: boto3)
+    AwsKmsConfig               — configuration for AwsKmsKeyProvider
+    AwsKmsKeyState             — mutable lifecycle state for AwsKmsKeyProvider
+    BotoKmsFacade              — boto3 adapter for AwsKmsKeyProvider
+    AwsKmsFacade               — abstract facade for testing without AWS
+
+Configuration loading (loaders parse; constructors default):
+    load_environment / load_file / load_cli_directory — one loader per source → LoadedConfig
+    LoadedConfig, LogTrust, KeySource — partial configuration shape shared by every source
+    merge_loaded_config        — field-wise merge of partial configurations (later wins)
+    construct_identity_manager — LoadedConfig + caller deps → IdentityManager
+    identity_manager_from_environment / identity_manager_from_dnsid / identity_manager_from_file
+    registry_client_from_environment — RegistryClient from DNSID_REGISTRY_URL / DNSID_API_KEY
+
+Interfaces (implement to integrate your own backends):
+    IdentityResolver  — minimal protocol satisfied by IdentityManager; accepted by profiles
+    KeyProvider       — key management (local files, KMS, HSM)
+    Log               — log write interface
+    LogReader         — log read/verify interface
+    IdentityCache     — verified domain cache
+    DNSResolver       — DNS resolver
+
+Errors:
+    ParseError        — structurally malformed TXT record
+    ValidationError   — semantic constraint violation
+    VerificationError — live verification failure (carries VerificationCode)
+    ArgumentError     — invalid caller-supplied argument
+
+Enumerations:
+    DNSSECState, DNSSECMode, VerificationCode, AgentState, RevocationReason,
+    RegistryRevocationReason, EventType
+"""
+
+from ._verification_budget import remaining_seconds, verification_budget
+from .agent_status import active_status_document
+from .aws_kms_key_provider import (
+    AwsKmsConfig as AwsKmsConfig,
+)
+from .aws_kms_key_provider import (
+    AwsKmsFacade as AwsKmsFacade,
+)
+from .aws_kms_key_provider import (
+    AwsKmsKeyProvider as AwsKmsKeyProvider,
+)
+from .aws_kms_key_provider import (
+    AwsKmsKeyState as AwsKmsKeyState,
+)
+from .aws_kms_key_provider import (
+    BotoKmsFacade as BotoKmsFacade,
+)
+from .config_loading import (
+    KeySource,
+    LoadedConfig,
+    LogTrust,
+    construct_identity_manager,
+    identity_manager_from_dnsid,
+    identity_manager_from_environment,
+    identity_manager_from_file,
+    load_cli_directory,
+    load_environment,
+    load_file,
+    merge_loaded_config,
+    registry_client_from_environment,
+)
+from .conformance import SDK_CONFORMANCE, SDKConformance
+from .enums import (
+    AgentState,
+    DNSSECMode,
+    DNSSECState,
+    EventType,
+    LifecycleErrorCategory,
+    LogSignerRole,
+    RegistryRevocationReason,
+    RevocationReason,
+    VerificationCode,
+)
+from .exceptions import (
+    ArgumentError,
+    DNSidError,
+    LifecycleVerificationError,
+    ManagedKeyRotationActivationError,
+    ManagedKeyRotationSubmissionError,
+    ParseError,
+    RegistryRequestError,
+    ValidationError,
+    VerificationError,
+)
+from .http_signatures import HttpMessageSignatureConfig, HttpSignatureProfile
+from .interfaces import (
+    AbstractRegistryClient,
+    DNSResolver,
+    HTTPSFetcher,
+    IdentityCache,
+    IdentityResolver,
+    KeyProvider,
+    Log,
+    LogReader,
+    NoopLogReader,
+)
+from .jose import JoseConfig, JoseProfile
+from .local_key_provider import LocalKeyProvider
+from .manager import (
+    ApplicationSigningPauseHook,
+    IdentityManager,
+    IdentityManagerDependencies,
+    KeyRotationPersistenceHook,
+    sign_event_with_provider,
+)
+from .models import (
+    DEFAULT_REGISTRY_URL,
+    IDENTITY_RECORD_VERSION,
+    JWK,
+    JWKS,
+    AgentRegistration,
+    AgentRegistrationInput,
+    AgentStatus,
+    AnyLogEvent,
+    CanonicalRecordContentResponse,
+    DelegationEvent,
+    DnsidConfig,
+    DnsIdTxtRecord,
+    DomainLog,
+    DomainSnapshot,
+    HttpRequest,
+    HttpSigningOptions,
+    HttpVerificationOptions,
+    IdentityConfig,
+    IssuanceEvent,
+    JWTOptions,
+    KeyRotationEvent,
+    KeyRotationPreparationRequest,
+    KeyRotationResult,
+    LifecycleResult,
+    LiveAgentRegistrationInput,
+    LiveChallengeTranscript,
+    LiveProofReissueRequest,
+    LiveProofReissueResponse,
+    LiveProofRequest,
+    LiveProofResponse,
+    LiveProvisioningResponse,
+    LogEvent,
+    LoggedStateEvidence,
+    LogRef,
+    MigrationEvent,
+    PreparedRegistryEvent,
+    PublicationConfig,
+    PublishedRecord,
+    RegistryAgentStatus,
+    RegistryConfig,
+    RetirementEvent,
+    RevocationEvent,
+    SignatureParams,
+    SubmissionResult,
+    TLSCertificate,
+    TransportConfig,
+    TrustedEntity,
+    TXTRecord,
+    VerificationConfig,
+    VerifiedCutoffHistory,
+    VerifiedDomain,
+    check_ek_ku_distinctness,
+    publish_allowed_version,
+)
+from .oidc import (
+    NetworkError,
+    OAuthError,
+    OIDCAssertionOptions,
+    OIDCConfig,
+    OIDCDiscoveryDocument,
+    OIDCProfile,
+    OIDCTokenExchangeOptions,
+    OIDCTokenResponse,
+    VerifiedOIDCSubject,
+    VerifyOIDCTokenOptions,
+)
+from .registry import LogRegistry
+from .registry_client import RegistryClient
+from .retry import async_retry_transient, retry_transient
+from .wba_signer import (
+    WBADirectoryResponse,
+    WBAHttpSigner,
+    WBAVariant,
+    WebBotAuthConfig,
+    WebBotAuthSigningOptions,
+    serve_http_message_signatures_directory,
+)
+from .wba_verifier import WBAHttpVerifier, WebBotAuthVerificationOptions
+from .web_bot_auth import (
+    BotAuthConfig,
+    BotIdentity,
+    VerifiedBotRequest,
+    WebBotAuthProfile,
+)
+
+PROTOCOL_VERSION: str = IDENTITY_RECORD_VERSION
+"""Wire version string for the DNSid protocol implemented by this SDK.
+
+Alias of IDENTITY_RECORD_VERSION — the current numbered publish profile.
+"""
+
+__all__ = [
+    # Core
+    "IdentityManager",
+    "IdentityManagerDependencies",
+    # Config
+    "DnsidConfig",
+    "IdentityConfig",
+    "VerificationConfig",
+    "TrustedEntity",
+    "TransportConfig",
+    "RegistryConfig",
+    # DNS record
+    "DnsIdTxtRecord",
+    "TXTRecord",
+    # Keys
+    "JWK",
+    "JWKS",
+    "check_ek_ku_distinctness",
+    # Status / TLS
+    "AgentStatus",
+    "TLSCertificate",
+    # Verification result
+    "VerifiedDomain",
+    # Log
+    "DomainLog",
+    "DomainSnapshot",
+    "LoggedStateEvidence",
+    "VerifiedCutoffHistory",
+    "LogRef",
+    "LogEvent",
+    "AnyLogEvent",
+    "IssuanceEvent",
+    "KeyRotationEvent",
+    "RevocationEvent",
+    "RetirementEvent",
+    "MigrationEvent",
+    "DelegationEvent",
+    "LifecycleErrorCategory",
+    "LifecycleVerificationError",
+    "ManagedKeyRotationActivationError",
+    "ManagedKeyRotationSubmissionError",
+    "LogSignerRole",
+    "sign_event_with_provider",
+    # Registry
+    "LogRegistry",
+    "RegistryClient",
+    "AgentRegistrationInput",
+    "AgentRegistration",
+    "LifecycleResult",
+    "LiveAgentRegistrationInput",
+    "LiveChallengeTranscript",
+    "LiveProvisioningResponse",
+    "LiveProofRequest",
+    "LiveProofResponse",
+    "LiveProofReissueRequest",
+    "LiveProofReissueResponse",
+    "RegistryAgentStatus",
+    "CanonicalRecordContentResponse",
+    "PublishedRecord",
+    "PreparedRegistryEvent",
+    "KeyRotationPreparationRequest",
+    "KeyRotationResult",
+    "KeyRotationPersistenceHook",
+    "ApplicationSigningPauseHook",
+    "SubmissionResult",
+    # Application-layer option types
+    "JWTOptions",
+    "HttpRequest",
+    "HttpSigningOptions",
+    "HttpVerificationOptions",
+    "SignatureParams",
+    # JOSE / HTTP signatures profiles
+    "JoseProfile",
+    "JoseConfig",
+    "HttpSignatureProfile",
+    "HttpMessageSignatureConfig",
+    # OIDC profile
+    "OIDCProfile",
+    "OIDCConfig",
+    "OIDCAssertionOptions",
+    "OIDCTokenExchangeOptions",
+    "OIDCTokenResponse",
+    "OIDCDiscoveryDocument",
+    "VerifyOIDCTokenOptions",
+    "VerifiedOIDCSubject",
+    # Key management
+    "LocalKeyProvider",
+    # Configuration loading
+    "LoadedConfig",
+    "LogTrust",
+    "KeySource",
+    "load_environment",
+    "load_file",
+    "load_cli_directory",
+    "merge_loaded_config",
+    "construct_identity_manager",
+    "identity_manager_from_environment",
+    "identity_manager_from_dnsid",
+    "identity_manager_from_file",
+    "registry_client_from_environment",
+    # Agent status helpers
+    "active_status_document",
+    # Interfaces
+    "AbstractRegistryClient",
+    "IdentityResolver",
+    "KeyProvider",
+    "Log",
+    "LogReader",
+    "NoopLogReader",
+    "IdentityCache",
+    "DNSResolver",
+    "HTTPSFetcher",
+    # Retry helpers
+    "retry_transient",
+    "async_retry_transient",
+    # Conformance
+    "SDKConformance",
+    "SDK_CONFORMANCE",
+    "verification_budget",
+    "remaining_seconds",
+    "PROTOCOL_VERSION",
+    "PublicationConfig",
+    "DEFAULT_REGISTRY_URL",
+    "IDENTITY_RECORD_VERSION",
+    "publish_allowed_version",
+    # Web Bot Auth profile
+    "WBAHttpSigner",
+    "WBAHttpVerifier",
+    "WebBotAuthVerificationOptions",
+    "WBAVariant",
+    "WBADirectoryResponse",
+    "WebBotAuthConfig",
+    "WebBotAuthSigningOptions",
+    "serve_http_message_signatures_directory",
+    "WebBotAuthProfile",
+    "BotAuthConfig",
+    "BotIdentity",
+    "VerifiedBotRequest",
+    # Errors
+    "DNSidError",
+    "ParseError",
+    "ValidationError",
+    "RegistryRequestError",
+    "VerificationError",
+    "ArgumentError",
+    "NetworkError",
+    "OAuthError",
+    # Enumerations
+    "DNSSECState",
+    "DNSSECMode",
+    "VerificationCode",
+    "AgentState",
+    "RevocationReason",
+    "RegistryRevocationReason",
+    "EventType",
+]

dnsid/_crypto.py

@@ -0,0 +1,249 @@
+"""Cryptographic operations: JWK thumbprint, signature verification, and key parsing."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .models import JWK
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec, ed25519, padding, rsa
+from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+
+from ._utils import b64url_decode, b64url_encode
+
+# ---------------------------------------------------------------------------
+# RFC 7638 thumbprint
+# ---------------------------------------------------------------------------
+
+# Required public members per key type (alphabetical — the spec mandates this order).
+_THUMBPRINT_MEMBERS: dict[str, list[str]] = {
+    "EC": ["crv", "kty", "x", "y"],
+    "RSA": ["e", "kty", "n"],
+    "OKP": ["crv", "kty", "x"],
+}
+
+
+def compute_thumbprint(raw: dict[str, Any]) -> str:
+    """Return the RFC 7638 JWK thumbprint (SHA-256, unpadded base64url).
+
+    Raises ValueError if the key type is unsupported or required members are missing.
+    """
+    kty = raw.get("kty", "")
+    members = _THUMBPRINT_MEMBERS.get(kty)
+    if members is None:
+        raise ValueError(f"unsupported kty for thumbprint: {kty!r}")
+
+    missing = [k for k in members if k not in raw]
+    if missing:
+        raise ValueError(f"JWK missing required thumbprint members: {missing}")
+
+    canonical = {k: raw[k] for k in members}
+    canonical_json = json.dumps(canonical, separators=(",", ":"), sort_keys=True).encode("ascii")
+    digest = hashlib.sha256(canonical_json).digest()
+    return b64url_encode(digest)
+
+
+# ---------------------------------------------------------------------------
+# Signature verification
+# ---------------------------------------------------------------------------
+
+_EC_CURVES: dict[str, ec.EllipticCurve] = {
+    "P-256": ec.SECP256R1(),
+}
+
+# Number of bytes per integer component (r or s) — ES256 / P-256 only.
+_EC_COORD_BYTES: dict[str, int] = {
+    "ES256": 32,
+}
+
+_EC_HASH: dict[str, type[hashes.HashAlgorithm]] = {
+    "ES256": hashes.SHA256,
+}
+
+_RSA_HASH: dict[str, type[hashes.HashAlgorithm]] = {
+    "RS256": hashes.SHA256,
+}
+
+# Supported kty/crv → JOSE alg mappings (EdDSA and ES256 only per DNSid protocol).
+_KTY_CRV_TO_ALG: dict[tuple[str, str], str] = {
+    ("OKP", "Ed25519"): "EdDSA",
+    ("EC", "P-256"): "ES256",
+}
+
+
+def signature_alg_from_raw(raw: dict[str, Any]) -> str:
+    """Derive JOSE signature algorithm from kty/crv.
+
+    Raises ValueError if the kty/crv combination is not supported by the DNSid protocol.
+    """
+    kty = raw.get("kty", "")
+    crv = raw.get("crv", "")
+    alg = _KTY_CRV_TO_ALG.get((kty, crv))
+    if alg is None:
+        raise ValueError(
+            f"unsupported kty/crv for DNSid signature algorithm: kty={kty!r}, crv={crv!r}"
+        )
+    return alg
+
+
+_ALLOWED_ALGS: frozenset[str] = frozenset({"EdDSA", "ES256", "RS256"})
+
+
+def verify_signature(raw: dict[str, Any], payload: bytes, signature: bytes) -> bool:
+    """Return True if *signature* over *payload* is valid for the public key in *raw*.
+
+    Returns False for an invalid signature; never raises for a bad sig value.
+    When the JWK has no alg field, the algorithm is derived from kty/crv.
+    Only EdDSA and ES256 are accepted; any other algorithm returns False.
+    """
+    kty = raw.get("kty", "")
+    alg = raw.get("alg", "")
+
+    # Derive alg from kty/crv when absent (alg is optional per DNSid design).
+    if not alg:
+        try:
+            alg = signature_alg_from_raw(raw)
+        except ValueError:
+            return False
+
+    if alg not in _ALLOWED_ALGS:
+        return False
+
+    try:
+        if kty == "EC":
+            return _verify_ec(raw, alg, payload, signature)
+        if kty == "OKP":
+            return _verify_okp(raw, payload, signature)
+        if kty == "RSA":
+            return _verify_rsa(raw, alg, payload, signature)
+        return False
+    except InvalidSignature:
+        return False
+    except Exception:
+        return False
+
+
+def _verify_ec(raw: dict[str, Any], alg: str, payload: bytes, sig: bytes) -> bool:
+    crv = raw.get("crv", "")
+    curve = _EC_CURVES.get(crv)
+    if not curve:
+        raise ValueError(f"unsupported EC curve: {crv!r}")
+
+    hash_cls = _EC_HASH.get(alg)
+    if not hash_cls:
+        raise ValueError(f"unsupported EC alg: {alg!r}")
+
+    x = int.from_bytes(b64url_decode(raw["x"]), "big")
+    y = int.from_bytes(b64url_decode(raw["y"]), "big")
+    pub_key = ec.EllipticCurvePublicNumbers(x=x, y=y, curve=curve).public_key()
+
+    # JWT/JWS/RFC 9421 use IEEE P1363 (r || s); cryptography expects DER.
+    coord = _EC_COORD_BYTES.get(alg)
+    if coord and len(sig) == 2 * coord:
+        r = int.from_bytes(sig[:coord], "big")
+        s = int.from_bytes(sig[coord:], "big")
+        der_sig = encode_dss_signature(r, s)
+    else:
+        der_sig = sig  # fall through and let the library reject it
+
+    pub_key.verify(der_sig, payload, ec.ECDSA(hash_cls()))
+    return True
+
+
+def _verify_okp(raw: dict[str, Any], payload: bytes, sig: bytes) -> bool:
+    crv = raw.get("crv", "")
+    if crv != "Ed25519":
+        raise ValueError(f"unsupported OKP curve: {crv!r}")
+    pub_key = ed25519.Ed25519PublicKey.from_public_bytes(b64url_decode(raw["x"]))
+    pub_key.verify(sig, payload)
+    return True
+
+
+def _verify_rsa(raw: dict[str, Any], alg: str, payload: bytes, sig: bytes) -> bool:
+    hash_cls = _RSA_HASH.get(alg)
+    if not hash_cls:
+        raise ValueError(f"unsupported RSA alg: {alg!r}")
+    n = int.from_bytes(b64url_decode(raw["n"]), "big")
+    e = int.from_bytes(b64url_decode(raw["e"]), "big")
+    pub_key = rsa.RSAPublicNumbers(e=e, n=n).public_key()
+    pub_key.verify(sig, payload, padding.PKCS1v15(), hash_cls())
+    return True
+
+
+# ---------------------------------------------------------------------------
+# JWK construction from wire format
+# ---------------------------------------------------------------------------
+
+
+def jwk_from_dict(d: dict[str, Any]) -> JWK:
+    """Build a JWK dataclass from a raw dict (e.g. from a parsed JWKS JSON response)."""
+    from .models import JWK  # lazy import — models imports _utils, not _crypto
+
+    return JWK(
+        kty=d.get("kty", ""),
+        alg=d.get("alg", ""),
+        kid=d.get("kid", ""),
+        use=d.get("use", ""),
+        _raw=dict(d),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers for building a JWK dict from a cryptography private/public key
+# (used in tests to produce valid _raw dicts)
+# ---------------------------------------------------------------------------
+
+
+def ec_public_jwk_dict(
+    private_key: ec.EllipticCurvePrivateKey, kid: str, alg: str
+) -> dict[str, Any]:
+    """Produce a public JWK dict from a cryptography EC private key (ES256/P-256 only)."""
+    pub = private_key.public_key()
+    numbers = pub.public_numbers()
+    crv = {"secp256r1": "P-256"}[pub.curve.name]
+    coord_len = _EC_COORD_BYTES[alg]
+    return {
+        "kty": "EC",
+        "kid": kid,
+        "alg": alg,
+        "use": "sig",
+        "crv": crv,
+        "x": b64url_encode(numbers.x.to_bytes(coord_len, "big")),
+        "y": b64url_encode(numbers.y.to_bytes(coord_len, "big")),
+    }
+
+
+def ed25519_public_jwk_dict(private_key: ed25519.Ed25519PrivateKey, kid: str) -> dict[str, Any]:
+    """Produce a public JWK dict from a cryptography Ed25519 private key."""
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+    pub_bytes = private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    return {
+        "kty": "OKP",
+        "kid": kid,
+        "alg": "EdDSA",
+        "use": "sig",
+        "crv": "Ed25519",
+        "x": b64url_encode(pub_bytes),
+    }
+
+
+def ec_sign(private_key: ec.EllipticCurvePrivateKey, alg: str, payload: bytes) -> bytes:
+    """Sign *payload* with an EC private key; return IEEE P1363 (r||s) bytes."""
+    from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature
+
+    hash_cls = _EC_HASH[alg]
+    der_sig = private_key.sign(payload, ec.ECDSA(hash_cls()))
+    r, s = decode_dss_signature(der_sig)
+    coord = _EC_COORD_BYTES[alg]
+    return r.to_bytes(coord, "big") + s.to_bytes(coord, "big")
+
+
+def ed25519_sign(private_key: ed25519.Ed25519PrivateKey, payload: bytes) -> bytes:
+    """Sign *payload* with an Ed25519 private key."""
+    return private_key.sign(payload)